Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/lisp/clx.lha/clx.doc

Text File | 1993-08-06 | 323KB | 8,491 lines

;;; -*- Mode:Text; Package:XLIB; Base:10; Fonts:(MEDFNT HL12B HL12BI) -*-

           **** very preliminary, incomplete version ****
               **** (under construction) ****

Please address all questions and comments to:
Dan Stenger
Texas Instruments
PO Box 655474, MS 238
Dallas, TX   75265
[phone]
[e-mail]



           CLX - Common LISP Language X Interface

                   X Window System

                Version 11, Release 3


Copyright (C) 1989 Texas Instruments Incorporated.

Permission is granted to any individual or institution to use, copy, modify,
and distribute this documentation, provided that this complete copyright and
permission notice is maintained, intact, in all copies and supporting
information.

Texas Instruments Incorporated provides this documentation "as is" without
express or implied warranty.



Copyright (C) 1985, 1986, 1987, 1988 Massachusetts Institute of Technology,
Cambridge, Massachusetts, and Digital Equipment Corporation, Maynard,
Massachusetts.

Permission to use, copy, modify and distribute this documentation for any
purpose and without fee is hereby granted, provided that the above copyright
notice appears in all copies and that both that copyright notice and this
permission notice appear in supporting documentation, and that the name of
M.I.T.  or Digital not be used in in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.
M.I.T and Digital makes no representations about the suitability of the
software described herein for any purpose.  It is provided "as is" without
express or implied warranty.



The X Window System is a trademark of MIT.

UNIX is a trademark of AT&T Bell Laboratories.

ULTRIX, ULTRIX-32, ULTRIX-32m, ULTRIX-32w, and VAX/VMS are trademarks of
Digital Equipment Corporation.



                   Acknowledgments


        Primary Interface Author:
            Robert W. Scheifler
            MIT Laboratory for Computer Science
            545 Technology Square, Room 418
            Cambridge, MA   02139
            [e-mail]

        Primary Implementation Author:
            LaMott Oren
            Texas Instruments
            PO Box 655474, MS 238
            Dallas, TX   75265
            [e-mail]

        Design Contributors:
            Dan Cerys, Texas Instruments
            Scott Fahlman, CMU
            Kerry Kimbrough, Texas Instruments
            Chris Lindblad, MIT
            Rob MacLachlan, CMU
            Mike McMahon, Symbolics
            David Moon, Symbolics
            Michael Myjak, Texas Instruments
            LaMott Oren, Texas Instruments
            Daniel Weinreb, Symbolics
            John Wroclawski, MIT
            Richard Zippel, Symbolics



                  Table of Contents



    Chapter 1:  Introduction to CLX

    1.1.  Overview of the X Window System

    1.2.  Naming and Argument Conventions

    1.3.  Programming Considerations

    1.4.  Common Data Types

    1.5.  Complex Data Types


    Chapter 2:  Displays

    2.1.  Opening the Display

    2.2.  Display Functions

    2.3.  Display Attributes

    2.3.1.  After-Function, Finish-Output, Force-Output

    2.3.2.  Authorization-Data, Authorization-Name, and Display

    2.3.3.  Bitmap-Format and Pixmap-Formats

        2.3.4.  Byte-Order and Image-LSB-First-P

        2.3.5.  Default-Screen, NScreens, and Roots

        2.3.6.  Error-Handler

    2.3.7.  Error Conditions

        2.3.8.  Keycode-Range, Max-Keycode, and Min-Keycode

        2.3.9.  Max-Request-Length, Motion-Buffer-Size, and Squish

        2.3.10.  PList

        2.3.11. Protocol-Major-Version, Protocol-Minor-Version,
                Protocol-Version, Release-Number, Vendor,
                Vendor-Name, and Version-Number

        2.3.11. Resource-ID-Base, Resource-ID-Mask, and XID

        2.3.12. XDefaults

        2.4.  Closing the Display

        2.5.  Connection Close Operations


        Chapter 3:  Screens

        3.1.  Screen Functions

        3.2.  Screen Attributes

        3.2.1.  Backing-Stores and Save-Unders-P

        3.2.2.  Black-Pixel and White-Pixel

        3.2.3.  Default-Colormap, Max-Installed-Maps,
                and Min-Installed-Maps

        3.2.4.  Depths

        3.2.5.  Event-Mask-At-Open

        3.2.6.  Height, Height-In-Millimeters, Width,
                and Width-In-Millimeters

        3.2.7.  PList

        3.2.8.  Root, Root-Depth, and Root-Visual


        Chapter 4:  Windows

        4.1.  Creating Windows

        4.2.  Obtaining Information About a Window

        4.3.  Window Configuration

        4.3.1.  Border-Width

        4.3.2.  X and Y Position

        4.3.3.  Width and Height

        4.3.4.  Depth

        4.3.5.  Stacking Priority

        4.4.  Window Attributes

        4.4.1.  Background

        4.4.2.  Border

        4.4.3.  Bit Gravity and Window Gravity

        4.4.4.  Backing-Store

        4.4.5.  Save-Under

        4.4.6.  Backing-Planes and Backing-Pixel

        4.4.7.  Event-Mask and Do-Not-Propagate-Mask

        4.4.8.  Override-Redirect

        4.4.10. Cursor

    4.4.11.    Font

    4.4.12. Atoms

        4.5.  Window Properties

        4.6.  Window Selections

        4.7.  Window Stacking Order

        4.8.  Window Hierarchy

        4.9.  Translating Window Coordinates

        4.10. Mapping Windows

        4.11. Unmapping Windows

        4.12. Destroying Windows


        Chapter 5:  Graphic Contexts

        5.1.  Creating Graphic Contexts

        5.2.  Graphic Context Functions

        5.3.  Graphic Context Attributes

        5.3.1.  Arc-Mode

        5.3.2.  Background and Foreground

        5.3.3.  Cap-Style and Join-Style

        5.3.4.  Clip-Mask, Clip-Ordering, Clip-X, Clip-Y, and Subwindow-Mode

        5.3.5.  Dash-Offset, Dashes, and Line-Style

        5.3.6.  Exposures

        5.3.7.  Fill-Rule and Fill-Style

        5.3.8.  Font

        5.3.9.  Function and Plane-Mask

        5.3.10. Line-Width

        5.3.11. Stipple, Tile, TS-X, and TS-Y

        5.4.  Copying Graphic Contexts

        5.5.  Destroying Graphic Contexts

        5.6.  Graphic Context Cache



    Chapter 6:  Graphics Resource Functions

    6.1.  Colormaps and Colors

    6.1.1.  Color Functions

    6.1.2.  Color Cell Functions

    6.1.3.  Colormap Functions

    6.1.4  Color cells and planes

    6.2.  Manipulating Colors

    6.3.  Pixmaps

****----preliminary section designations

    6.4. Manipulating Graphics Context/State

    6.5. Using GC Convenience Routines

    6.5.1. Setting the Foreground, Background, Plane Mask, or Function

    6.5.2. Setting the Line Attributes and Dashes

    6.5.3. Setting the Fill Style and File Rule

    6.5.4. Setting the Fill Tile and Stipple

    6.5.5. Setting the Current Font

    6.5.6. Setting the Clip Region

    6.5.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure



        Chapter 7:  Graphic Operations

        7.1.  Area and Plane Operations

        7.2.  Drawing Points

        7.3.  Drawing Lines

        7.4.  Drawing Rectangles

        7.5.  Drawing Arcs


      Chapter 8: Events and Event-Handling Functions ........  216

****----preliminary section designations

      8.1. Event Types

      8.2. Event Structures

      8.3. Event Mask

      8.4. Event Processing

      8.4.1. Keyboard and Pointer Event Processing

      8.4.2. Window Entry/Exit Event Processing

      8.4.3. Input Focus Events

      8.4.4. Key Map State Notification Event Processing

      8.4.5. Exposure Event Processing

      8.4.6. Window State Notification Event Processing

      8.4.7. Structure Control Event Processing


      8.4.8. Color Map State Notification Event Processing

      8.4.9. Client Communication Event Processing

      8.5. Selecting Events

      8.6. Handling the Output Buffer

      8.7.  Event Queue Management

      8.8. Manipulating the Event Queue

      8.8.1. Returning the Next Event

      8.8.2. Selecting Events Using a Predicate Procedure

      8.8.3. Selecting Events Using a Window or Event Mask

      8.9. Putting an Event Back onto the Queue

      8.10. Sending Events to Other Applications

      8.11. Getting Pointer Motion History

      8.12. Handling Error Events

      8.12.1. Enabling or Disabling Synchronization

      8.12.2. Using the Default Error Handlers




    Chapter 9: Window Manager Functions

****----preliminary section designations

    9.1.  Changing the Parent

    9.2.  Lifetime of a Window

    9.3.  Resident Colormap Determination

    9.4.  Grab Operations

    9.4.1. Grabbing the pointer

    9.4.2. Grabbing a button

    9.4.3.  Grabbing the Keyboard

    9.4.4.  Grabbing a key

    9.4.5.  Grabbing the Server

    9.5.  Miscellaneous Control Functions

    9.6.  Keyboard Settings

    9.7.  Keyboard Encodings

    9.8. Screen Saver Utility

    9.9. Controlling Host Access



    Chapter ??:  Defining Extensions


    Appendix

    Glossary of Terms


      NOTE: all of the following LISP symbols are in the package XLIB.



                  Chapter 1

                 Introduction to CLX


The X Window System is a network transparent window system that was designed
at MIT and that runs under 4.3BSD UNIX, ULTRIX-32, many other UNIX variants,
VAX/VMS, MS/DOS, as well as several other operating systems.

X display servers run on computers with either monochrome or color bitmap
display hardware.  The server distributes user input to and accepts output
requests from various client programs located either on the same machine or
elsewhere in your network.  CLX is a Common LISP subroutine library that
application programs (clients) use to interface with the window system by
means of a stream connection.  Although a client often runs on the same
machine as the X server it is talking to, this need not be the case.

This manual is a reference guide to the low-level Common LISP language
interface to the X Window System protocol.  It is neither a tutorial nor a
user guide to programming to the X Window System.  Other high-level
abstractions (for example, the Common LISP User-Interface Environment, CLUE)
are built on top of the CLX library.  For further information about these
high-level libraries, see the appropriate documentation.  For general
information about the design of X, see "The X Window System".  The X Window
System Protocol provides the definitive word on the behavior of X.  So,
while additional information is provided by this manual, the protocol
document is the ruling document.

This manual assumes a basic understanding of a window system and of the
Common LISP programming language.  To provide an introduction to CLX
programming, this chapter discusses:

o    Overview of the X Window System

o    Naming and argument conventions

o    Programming considerations


1.1.  Overview of the X Window System

Some of the terms used in this book are unique to X, while other terms that
are common to other window systems have different meanings in X.  You may
find it helpful to refer to the glossary, located at the end of the book,
when you are uncertain of a terms meaning in the context of the X Window
System.

The X Window System supports one or more screens containing overlapping
windows or subwindows.  A screen is a physical monitor and hardware, which
may be either color or black and white.  There can be multiple screens per
display or workstation.  A single server can provide display services for
any number of screens.  A set of screens for a single user with one keyboard
and one mouse is called a "display".

All the windows in an X server are arranged in a strict hierarchy.  At the
top of the hierarchy are the root windows, which cover each of the display
screens.  Each root window is partially or completely covered by child
windows.  All windows, except for root windows, have parents.  There is
usually at least one window per application program.  Child windows may in
turn have their own children.  In this way, an application program can
create a tree of arbitrary depth on each screen.

A child window may be larger than its parent.  That is, part or all of the
child window may extend beyond the boundaries of the parent.  However, all
output to a window is clipped by the boundaries of its parent window.  If
several children of a window have overlapping locations, one of the children
is considered to be on top of or raised over the others, obscuring them.
Output to areas covered by other windows will be suppressed by the window
system.  If a window is obscured by a second window, the second window will
obscure only those ancestors of the second window, which are also ancestors
of the first window.

A window has a border of zero or more pixels in width, which can be any
pattern (pixmap) or solid color you like.  A window usually but not always
has a background pattern which will be repainted by the window system when
uncovered.  Each window has its own coordinate system.  Child windows
obscure their parents unless the child windows have no background, and
graphic operations in the parent window usually are clipped by the children.

Input from X takes the form of events.  Events may either be side effects of
a command (for example, restacking windows generates exposure events) or
completely asynchronous (for example, the keyboard).  A client program asks
to be informed of events.  Programs must be prepared to handle (OR ignore)
events of all types, because other applications can send events to your
application.

X does not take responsibility for the contents of windows.  When part or
all of a window is hidden and then brought back onto the screen, its
contents may be lost, and the client program is notified (by an exposure
event) that part or all of the window needs to be repainted.  Programs must
be prepared to regenerate the contents of windows on demand.

X also provides off screen storage of graphics objects, called "pixmaps".
Single plane (depth 1) pixmaps are sometimes referred to as "bitmaps".
These can be used in most graphics functions interchangeably with windows,
and are used in various graphic operations to define patterns also called
"tiles".  Windows and pixmaps together are referred to as "drawables".

Most of the functions in CLX just add requests to an output buffer.  These
requests later execute asynchronously on the X server, often referred to as
display server.  Functions that return values of information stored in the
server do not return (that is, they "block") until an explicit reply is
received or an error occurs.  If a nonblocking call results in an error, the
error will generally not be reported by a call to an optional error handler
until some later, when a blocking call is made.

If it does not want a request to execute asynchronously, a client can follow
it with a call to display-finish-output, which will block until all
previously buffered asynchronous events have been sent and acted on.  As an
important side effect, the output buffer is always flushed by a call to any
function which returns a value from the server or waits for input (for
example, get-property, process-event, or display-finish-output).

Many CLX functions will return an integer resource ID, which allows you to
refer to objects stored on the X server.  These can be of type Window, Font,
Pixmap, Bitmap, Cursor, and GContext.  These resources are created by user
requests, and destroyed (OR freed) by user requests or when connections are
closed.  Most of these resources are potentially sharable between
applications, and in fact, windows are manipulated explicitly by window
manager programs.  Fonts and cursors are typically shared automatically
since the X server treats fonts specially, loading and unloading font
storage as needed.  GContexts should not be shared between applications.

All errors (synchronous and asynchronous) are processed by calling an error
handler in the display.  If the handler is a sequence it is expected to
contain handler functions specific to each error.  The error code is used to
index the sequence, fetching the appropriate handler.  Any results returned
by the handler are ignored since it is assumed that the handler either takes
care of the error completely, or else signals.

Input events (for example, key pressed or mouse moved) arrive asynchronously
from the server and are queued until they are requested by an explicit call
(for example, event-case or process-event).  In addition, some of the CLX
functions (for example, SETF of some window attributes) generate exposure
events (that is, requests to repaint sections of a window that do not have
valid contents).  These events also arrive asynchronously, but the client
may wish to explicitly wait for them by calling display-finish-output after
calling a function which may generate exposure events.


1.2.  Naming and Argument Conventions

Throughout CLX, a number of conventions for naming and syntax of the CLX
functions have been followed.  These conventions are intended to make the
syntax of the functions more predictable, given that you remember what
information the routine may require.

The major naming conventions are:

o    To better differentiate the CLX symbols from the other symbols they
     have all been places in the package XLIB.  External symbols have been
     explicitly exported.

o    The display argument, where used, is always first in the argument list.

o    All resource objects, where used, occur at the beginning of the
     argument list, immediately after the display variable.

o    When a graphic context is present together with another type of
     resource (most commonly, a drawable), the graphic context occurs in the
     argument list after the other resource.  Drawables out rank all other
     resources.

o    Source arguments always precede the destination arguments in the
     argument list.

o    The x argument always precedes the y argument in the argument list.

o    The width argument always precedes the height argument in the argument
     list.

o    Where the x, y, width and height arguments are used together, the x and
     y arguments always precede the width and height arguments.

o    Where a mask is accompanied with a structure, the mask always precedes
     the structure in the argument list.


1.3.  Programming Considerations

The major considerations are:

o    Keyboards are the greatest variable between different manufacturer's
     workstations.  If you want your program to be portable, you should be
     particularly conservative here.

o    Many display systems have limited amounts of off-screen memory.  If you
     can, you should minimize use of pixmaps and backing store.

o    The user should have control of his screen real-estate.  Therefore, you
     should write your applications to react to window management, rather
     than presume control of the entire screen.  What you do inside of your
     top level window, however, is up to your application.

o    Coordinates and sizes in X are actually 16-bit quantities.  They
     usually are declared as an "int16" in the functions.  Values larger
     than 16 bits may be truncated silently.  Sizes (width and height) are
     unsigned quantities.

o    The types: color, colormap, cursor, display, font, gcontext, pixmap,
     screen, and window are defined solely by a functional interface.  Even
     though they are talked about as structures in this document, it is not
     specified whether they are implemented as structures, flavors, or
     whatever.  So, although functions below are written using DEFUN, this
     is not an implementation requirement (it is a requirement that they be
     functions as opposed to macros or special forms).


1.4. Common Data Types

The following are some data type definitions that are commonly used in CLX
function definitions.


(DEFTYPE alist (key-type-and-name datum-type-and-name) 'list)

The type alist defines an association list.  An association list is a
sequence, containing zero or more repetitions of the given elements, with the
elements expressed as (type name).


(DEFTYPE angle () `(NUMBER ,(* -2 pi) ,(* 2 pi)))

The angle type is used to define an angle, in units of radians and is bounded
by (* -2 pi) and (* 2 pi).  Note that we are explicitly using a different
angle representation than what is actually transmitted in the protocol.


(DEFTYPE arc-seq () '(repeat-seq
            (int16 x) (int16 y) (card16 width) (card16 height)
            (angle angle1) (angle angle2)))

The arc-seq type is used to define a six-tuple sequence of the form
(X,Y,Width,Height,Angle1,Angle2).  The points X and Y are signed, 16-bit
quantities with a range from -32,768 to 32,767.  The Width and Height values
are unsigned, 16-bit quantities and range from 0 to 65,535.  Angle1 and Angle2
in units of radians and bounded by (* -2 pi) and (* 2 pi).


(DEFTYPE array-index () `(INTEGER 0 ,array-dimension-limit))

This defines a type which is a subtype of the integers and can be used to
describe all variables that can be array indices.  The range is inclusive
because start and end array index specifiers can be 1 past the end.


(DEFTYPE boolean () '(OR null (NOT null)))

This defines a type which is all inclusive.  It is used for variables that
can take on a true (non-null) or false (NIL) value.


(DEFTYPE boole-constant ()
  `(MEMBER ,BOOLE-CLR ,BOOLE-AND ,BOOLE-ANDC2 ,BOOLE-1
           ,BOOLE-ANDC1 ,BOOLE-2 ,BOOLE-XOR ,BOOLE-IOR
           ,BOOLE-NOR ,BOOLE-EQV ,BOOLE-C2 ,BOOLE-ORC2
           ,BOOLE-C1 ,BOOLE-ORC1 ,BOOLE-NAND ,BOOLE-SET))

This defines a type which is a set of the values associated with the sixteen
boolean operation-code constants for the Common LISP language.  It is used
for the set of allowed source and destination combination functions in a
graphic context.


(DEFTYPE card8 () '(unsigned-byte 8))

The type card8 is an unsigned integer value that is a maximum of 8 bits
long.  This gives a number of this type a range from 0 to 255.


(DEFTYPE card16 () '(unsigned-byte 16))

The type card16 is an unsigned integer value that is a maximum of 16 bits
long.  This gives a number of this type a range from 0 to 65,535.


(DEFTYPE card29 () '(unsigned-byte 29))

The type card29 is an unsigned integer value that is a maximum of 29 bits
long.  This gives a number of this type a range from 0 to 536,870,911.


(DEFTYPE card32 () '(unsigned-byte 32))

The type card32 is an unsigned integer value that is a maximum of 32 bits
long.  This gives a number of this type a range from 0 to 4,294,967,295.


(DEFTYPE drawable () '(OR window pixmap))

Both windows and pixmaps may be used as sources and destinations in graphics
operations.  These are collectively known as drawables.  However, an input
only window cannot be used as a source or destination in a graphics
operation.


(DEFTYPE draw-direction ()
  '(MEMBER :left-to-right :right-to-left))

The draw-direction type defines a list of rotation directions for drawing
arcs and fonts.  Draw-direction may have the values of :left-to-right
or :right-to-left.

(DEFTYPE error-key ()
  '(MEMBER :access :alloc :atom :colormap :cursor :drawable :font :gcontext
       :id-choice :illegal-request :implementation :length :match :name
       :pixmap :value :window))

All errors (synchronous and asynchronous) are processed by calling an error
handler in the display.  The handler is called with the display as the first
argument and the error-key as its second argument.  The error-key type defines
a list of all predefined errors.


(DEFTYPE event-key ()
  '(MEMBER :key-press :key-release :button-press :button-release
           :motion-notify :enter-notify :leave-notify :focus-in :focus-out
           :keymap-notify :exposure :graphics-exposure :no-exposure
           :visibility-notify :create-notify :destroy-notify :unmap-notify
           :map-notify :map-request :reparent-notify :configure-notify
           :gravity-notify :resize-request :configure-request
           :circulate-notify :circulate-request :property-notify
           :selection-clear :selection-request :selection-notify
           :colormap-notify :client-message))

Clients are informed of information asynchronously by means of "events." These
events may be either asynchronously generated from devices, or generated as
side effects of client requests.  The event-key type defines a list that
specifies all predefined event types.


(DEFTYPE fontable () '(OR stringable font))

A fontable is either a font object or the name of one of the fonts in the
font database.


(DEFTYPE font-props () 'list)

The font-props type is a list which contains alternating keywords and
integers.


(DEFTYPE gcontext-key ()
  '(MEMBER :function :plane-mask :foreground :background
       :line-width :line-style :cap-style :join-style :fill-style :fill-rule
       :arc-mode :tile :stipple :ts-x :ts-y :font :subwindow-mode
       :exposures :clip-x :clip-y :clip-mask :dash-offset :dashes))

Various information for graphics output is stored in a "graphics context"
("GC" or "GContext"), such as foreground pixel, background pixel, line width,
clipping region, etc.  The Gcontext-key type is a list of predefined types for
use in gcontext processing.


(DEFTYPE grab-status ()
  '(member :success :already-grabbed :frozen :invalid-time :not-viewable))


There are two kinds of grabs: active and passive.  An active grab occurs when
a single client grabs the keyboard and/or pointer explicitly.  Clients can
also grab a particular keyboard key or pointer button in a window.  The grab
activates when the key or button is actually pressed, and is called a "passive
grab".  Passive grabs can be very convenient for implementing reliable pop-up
menus.


(DEFTYPE image-depth () '(INTEGER 0 32))

The image-depth type is used in determining the depth of a pixmap, window or
image.  The value specifies the number of bits "deep" that a given pixel has
within a given pixmap, window or image.


(DEFTYPE int8 () '(signed-byte 8))

The type int8 is an signed integer value that is a maximum of 8 bits long.
This gives a number of this type a range from -128 to 127.


(DEFTYPE int16 () '(signed-byte 16))

The type int16 is an signed integer value that is a maximum of 16 bits long.
This gives a number of this type a range from -32,768 to 32,767.


(DEFTYPE int32 () '(signed-byte 32))

The type int32 is an signed integer value that is a maximum of 32 bits long.
This gives a number of this type a range from -2,147,483,648 to
2,147,483,647.


(DEFTYPE keysym () 'card32)

The keysym type is used as an encoding of a symbol on a keycap on a keyboard.
It is an unsigned integer value represented in a maximum of 32 bits long.
This gives a keysym type a range from 0 to 4,294,967,295.


(DEFTYPE mask16 () 'card16)

The type mask16 is a positional bitmask that contains 16 boolean flags.


(DEFTYPE mask32 () 'card32)

The type mask32 is a positional bitmask that contains 32 boolean flags.


(DEFTYPE modifier-key ()
  '(MEMBER :shift :lock :control :mod-1 :mod-2 :mod-3 :mod-4 :mod-5) )

Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock, ShiftLock,
and similar keys are called modifier keys.  The modifier-key type is used to
define these system dependent keys.  The modifier keys for shift, lock, and
control are defined by the protocol, while the system dependent keys (:mod-1,
mod-2, etc.) are defined by keyboard mapping routines.


(DEFTYPE modifier-mask ()
  '(OR (MEMBER :any) mask16 (list modifier-key)))

The modifier-mask type is used to define a 16-bit mask. The mask may be any of
the modifier-key types, or :any.


(DEFTYPE pixel () '(unsigned-byte 32))

The type pixel is an unsigned integer value that is a maximum of 32 bits long.
This gives a pixel type a value range from 0 to 4,294,967,295.  Useful values
are dependent on the class of colormap being used.


(DEFTYPE point-seq () '(repeat-seq (int16 x) (int16 y)))

The point-seq type is used to define sequences of (X,Y) pairs of points.  The
paired values are 16-bit, signed integer quantities.  This gives the points
in this type a range from -32,768 to 32,767.


(DEFTYPE rect-seq () '(repeat-seq (int16 x) (int16 y)
                  (card16 width) (card16 height)))

The rect-seq type is used to define a four-tuple sequence of the form
(X,Y,Width,Height).  The points X, and Y are signed, 16-bit quantities with a
range from -32,768 to 32,767.  The Width and Height values are unsigned,
16-bit quantities and range from 0 to 65,535.


(DEFTYPE repeat-seq (&REST elts) 'sequence)

The repeat-seq type is a sub-type used to define repeating sequences.


(DEFTYPE resource-id () 'card29)

The type resource-id is a numeric identifier that is assigned by the server
to a resource object.


(DEFTYPE rgb-val () '(FLOAT 0.0 1.0))

An rgb-val is a floating point value between 0 and 1 that specifies a
saturation for a red, green, or blue additive primary.  The 0 value
indicates no saturation and 1 indicates full saturation.


(DEFTYPE seg-seq () '(repeat-seq (int16 x1) (int16 y1) (int16 x2) (int16 y2)))

The seg-seq type is used to define sequences of (X1,Y1,X2,Y2) sets of points.
The point values are 16-bit, signed integer quantities.  This gives the
points in this type a range from -32,768 to 32,767.


(DEFTYPE state-mask-key ()
  '(OR modifier-key (member :button-1 :button-2 :button-3 :button-4 :button-5)))

The state-mask-key type combines the modifier-key sub-type with the pointer
buttons.


(DEFTYPE stringable () '(OR STRING SYMBOL))

The type stringable is used for naming something.  It can be either a string
or a symbol whose SYMBOL-NAME is used as the string containing the name.
The case of the characters in the string is ignored when comparing
stringables.


(DEFTYPE timestamp () '(OR NULL card32))

The type timestamp is an encoding of a time.  NIL stands for the current
time.


(DEFTYPE xatom () '(OR STRING SYMBOL))

The type xatom is a name that has been assigned a corresponding unique id by
the server.  They are used to identify properties, selections, and types.
An xatom can be either a string or symbol whose SYMBOL-NAME is used as the
string containing the name.  The case of the characters in the string are
significant when comparing xatoms.

There are a number of xatoms that have predefined values.  These predefined
xatoms are not strictly necessary, and may not be useful in all
environments, but will eliminate many calls to intern-atom in most
applications.  Note that "predefined" is only in the sense of having
assigned id values, not in the sense of having required semantics.  The core
protocol imposes no semantics on these names, except as they are used in
FONTPROP structures (see query-font).

This is the list of predefined xatoms.  Remember that upper and lower case
matters.

        ARC                     ITALIC_ANGLE            STRING
        ATOM                    MAX_SPACE               SUBSCRIPT_X
        BITMAP                  MIN_SPACE               SUBSCRIPT_Y
        CAP_HEIGHT              NORM_SPACE              SUPERSCRIPT_X
        CARDINAL                NOTICE                  SUPERSCRIPT_Y
        COLORMAP                PIXMAP                  UNDERLINE_POSITION
        COPYRIGHT               POINT                   UNDERLINE_THICKNESS
        CURSOR                  POINT_SIZE              VISUALID
        CUT_BUFFER0             PRIMARY                 WEIGHT
        CUT_BUFFER1             QUAD_WIDTH              WINDOW
        CUT_BUFFER2             RECTANGLE               WM_CLASS
        CUT_BUFFER3             RESOLUTION              WM_CLIENT_MACHINE
        CUT_BUFFER4             RESOURCE_MANAGER        WM_COMMAND
        CUT_BUFFER5             RGB_BEST_MAP            WM_HINTS
        CUT_BUFFER6             RGB_BLUE_MAP            WM_ICON_NAME
        CUT_BUFFER7             RGB_COLOR_MAP           WM_ICON_SIZE
        DRAWABLE                RGB_DEFAULT_MAP         WM_NAME
        END_SPACE               RGB_GRAY_MAP            WM_NORMAL_HINTS
        FAMILY_NAME             RGB_GREEN_MAP           WM_SIZE_HINTS
        FONT                    RGB_RED_MAP             WM_TRANSIENT_FOR
        FONT_NAME               SECONDARY               WM_ZOOM_HINTS
        FULL_NAME               STRIKEOUT_ASCENT        X_HEIGHT
        INTEGER                 STRIKEOUT_DESCENT

To avoid conflicts with possible future names for which semantics might be
imposed (either at the protocol level or in terms of higher level user
interface models), names beginning with an underscore should be used for
xatoms that are private to a particular vendor or organization.  To
guarantee no conflicts between vendors and organizations, additional
prefixes need to be used, but the mechanism for choosing such prefixes is
not defined here.  For names private to a single application or end user,
but stored in "globally accessible" locations, it is suggested that two
leading underscores be used to avoid conflicts with other names.


1.5. Complex Data Types

The following are some complex data type definitions that are used in CLX.
The types: color, colormap, cursor, display, font, gcontext, pixmap, and
window are defined solely by a functional interface.  It is not specified
whether they are implemented as structures, flavors, or whatever.  So,
although functions below are written using DEFUN, this is not an
implementation requirement (it is a requirement that they be functions as
opposed to macros or special forms).

The types: colormap, cursor, font, gcontext, pixmap, screen, and window are
all represented as compound objects, rather than as integer resource-ids.
This allows applications to deal with multiple displays without having an
explicit display argument in the most common functions.  Every function uses
the display object indicated by the first argument.  It is considered an error
if arguments contain different displays, and predictable results are not
guaranteed.

Each of colormap, cursor, font, gcontext, pixmap, and window have the
following five functions associated with them:

(defun make-<mumble> (display resource-id)
  (declare (type display display)
       (type integer resource-id)
       (values <mumble>)))

(defun <mumble>-display (<mumble>)
  (declare (type <mumble> <mumble>)
       (values display)))

(defun <mumble>-id (<mumble>)
  (declare (type <mumble> <mumble>)
       (values integer)))

(defun <mumble>-equal (<mumble>-1 <mumble>-2)
  (declare (type <mumble> <mumble>-1 <mumble>-2)))

(defun <mumble>-p (<mumble>-1 <mumble>-2)
  (declare (type <mumble> <mumble>-1 <mumble>-2)
       (values boolean)))

This first function, make-<mumble>, should almost never be called by
applications, except possibly while handling events.  The other four routines:
-display, -id, -equal, and -p, are provided for user and are documented
individually, elsewhere in the body of this document.

(DEFTYPE color () '(SATISFIES color-p))

A color is a structure containing a triple of red, green, and blue values that
define a specific visible color.  It is a representation of a set of values
that could be stored in a color cell.  It contains all of the information
necessary to fully specify a specific visible color in a color cell.


(DEFTYPE colormap () '(SATISFIES colormap-p))

A colormap is an ordered collection of color cells.  For each possible value
a pixel may have on a display, there is a corresponding color cell in the
colormap.  For example, if a display is 4 bits deep there are entries for
pixel values from 0 through 15.


(DEFTYPE cursor () '(SATISFIES cursor-p))

A cursor is the visible shape of the (mouse) pointer on a screen.  The pointer
consists of a hot spot, a source bitmap, a shape bitmap, and a pair of colors.
The cursor, when defined for a given window, controls the visible appearance
of the pointer when the pointer is in that window.


(DEFTYPE display () '(SATISFIES display-p))

Applications should not directly modify any part of the display structure,
except where the elements are stated to be settable.  The other elements
should be considered read-only, although they may change as the result of
other operations on the display.


(DEFTYPE font () '(SATISFIES font-p))

A font is a matrix of glyphs (typically characters).  The protocol does no
translation or interpretation of character sets.  The client simply indicates
values used to index the glyph array.  A font contains additional metric
information to determine inter-glyph and inter-line spacing.


(DEFTYPE gcontext () '(SATISFIES gcontext-p))

Applications should not directly modify any part of the graphic context,
except where the elements are stated to be settable.  The other elements
should be considered read-only, although they may change as the result of
other operations on the graphic context.


(DEFTYPE pixmap () '(SATISFIES pixmap-p))

A pixmap is a three dimensional array of bits.  A pixmap is normally thought
of as a two dimensional array of pixels, where each pixel can be a value from
0 to (2^N)-1, where N is the depth (z axis) of the pixmap.  A pixmap can also
be thought of as a stack of N bitmaps.


(DEFTYPE screen () '(SATISFIES screen-p))

Applications should not directly modify any part of the screen structure,
except where the elements are stated to be settable.  The elements should be
considered read-only, although they may change as the result of other
operations on the screen.


(DEFTYPE window () '(SATISFIES window-p))

Applications should not directly modify any part of the window structure,
except where the elements are stated to be settable.  The other elements
should be considered read-only, although they may change as the result of
other operations on the window.





                  Chapter 2

                                  Displays


A particular X server, together with its screens and input devices, is
called a display.  The CLX display structure contains all the information
about the particular display and its screens, as well as the state that is
needed to communicate with the display over a particular connection.

Before your program can use a display, you must establish a connection to
the X server driving your display.  Once you have established a connection,
you then can use the CLX macros and functions discussed in this chapter to
return information about the display.  This chapter discusses how to:

o    Open (connect) a display

o    Obtain information about a display

o    Access and change display attributes

o    Close (disconnect) a display

Finally, the chapter concludes with a section that describes the operations
that occur when the connection to the X server is closed.


2.1.  Opening the Display

This section lists the Common LISP language functions and the data that they
require for opening a connection to an X server.


(DEFUN open-display (host &key (display 0) protocol)
  (DECLARE (TYPE integer :display)
           (VALUES display-structure)
           (TYPE display display-structure)))

host    Specifies the name of the host machine on which the display is
        physically attached.  A string must be acceptable as a host, but
        otherwise the possible types are not constrained, and will likely be
        very system dependent.

:display
        A keyword argument that specifies which screen on the host server
        for this connection should normally be used.  This is needed since
        multiple screens can be connected to or controlled by a single X
        server.  This argument is used to set an internal variable that can
        be accessed by using the display-default-screen function.  The
        default is to select screen zero.

:protocol
        A keyword argument that specifies the network protocol which should
        be used for connecting to the server (something like :TCP :DNA or
        :CHAOS).  The set of possible values and the default value are
        implementation specific.  Authorization, if any, is assumed to come
        from the environment somehow.

The open-display function returns a display structure that serves as the
connection to the X server and that contains all the information about that
X server.  Open-display connects the specified hardware display to the
server through TCP, UNIX domain, or DECnet stream communications protocols.
A single server can support any or all of these transport mechanisms
simultaneously.

After a successful call to open-display, all of the screens in the display
may be used by the client application.  The screen number specified in the
display argument will be returned by the display-default-screen function.
You can access elements of the display and screen structures by using the
accessor functions or macros.


2.2.  Display Functions

CLX provides a number of useful functions that return data from a display
structure.  All other elements (that is, those for which no functions are
defined) are internal to CLX and must not be used.  An example of this is the
CLX No-Operation request.  The following lists the Common LISP language
functions and what data they return for the specified display structure.


(DEFUN display-p (display)
  (DECLARE (TYPE T display)
       (VALUES display?)
           (TYPE boolean display?)))

display The data object which is to be tested to see if it is a display.

This function returns non-null if the argument is a display structure,
otherwise it returns NIL.


(DEFUN colormap-display (colormap)
  (DECLARE (TYPE colormap colormap)
       (VALUES display?)
       (TYPE boolean display?)))

colormap
    Specifies the colormap whose display element is to be accessed.

This function returns the display that the specified colormap object is
associated with.


(DEFUN cursor-display (cursor)
   (DECLARE (TYPE cursor cursor)
            (VALUES display?)
            (TYPE boolean display?)))

cursor    The cursor object to be accessed.

This function returns the display that is associated with the specified cursor
object.


(DEFUN font-display (font)
   (DECLARE (TYPE font font)
        (VALUES display?)
            (TYPE boolean display?)))

font    The glyph array to be accessed.

This function returns the display that is associated with the specified font
object.


(DEFUN gcontext-display (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES display?)
           (TYPE display display?)))

gcontext
        The graphic context whose display is to be accessed.

This function returns the display that is associated with the specified
graphic context.


(DEFUN pixmap-display (pixmap)
   (DECLARE (TYPE pixmap pixmap)
        (VALUES display?)
            (TYPE boolean display?)))

pixmap    A three dimensional array of bits whose display is to be returned.

This function returns the display that is associated with the specified pixmap
object.


(DEFUN window-display (window)
  (DECLARE (TYPE window window)
           (VALUES display?)
           (TYPE display display?)))

window  The window structure which is to be accessed.

This function returns the display that is associated with the specified
window structure.


(DEFMACRO with-display ((display) &body body))

display The display structure which is to be accessed.


This macro is for use in a multi-process environment.  It provides exclusive
access to the local display object for multiple request generation.  It need
not provide immediate exclusive access for replies.  That is, if another
process is waiting for a reply (while not in a with-display), then
synchronization need not (but can) occur immediately.  Except where noted, all
routines effectively contain an implicit with-display where needed, so that
correct synchronization is always provided at the interface level on a
per-call basis.  Nested uses of this macro will work correctly.  This macro
does not prevent concurrent event processing (see with-event-queue).


2.3.  Display Attributes

The complete set of display attributes are discussed in the following
sections.


2.3.1.  After-Function, Finish-Output, Force-Output


(DEFUN display-after-function (display)
  (DECLARE (TYPE display display)
           (VALUES after-function)
           (TYPE (OR NULL (FUNCTION (display))) after-function)))

Settable.

display The display structure which is to be accessed.

If this element is non-null it is a function that is called after every
protocol request is generated, even those inside an explicit with-display, but
never called from inside the after-function itself.  The function is called
inside the effective with-display for the associated request.  The default
value is NIL.  This can be set, for example, to #'display-force-output or
#'display-finish-output.


(DEFUN display-finish-output (display)
  (DECLARE (TYPE display display)))

display The display structure which is to be accessed.

Forces output, then causes a round-trip to ensure that all possible errors and
events have been received.


(DEFUN display-force-output (display)
  (DECLARE (TYPE display display)))

display The display structure which is to be accessed.

Output is normally buffered.  This function forces any buffered output to
occur.


2.3.2.  Authorization-Data, Authorization-Name, and Display


(DEFUN display-authorization-data (display)
  (DECLARE (TYPE display display)
           (VALUES authorization-data)
           (TYPE string authorization-data)))

display The display structure which is to be accessed.

This functions returns the authorization data string that was transmitted to
the server during connection setup during the call to open-display.  The
data is specific to the particular authorization protocol that was used.
The display-authorization-name function returns the protocol used.


(DEFUN display-authorization-name (display)
  (DECLARE (TYPE display display)
           (VALUES authorization-name)
           (TYPE string authorization-name)))

display The display structure which is to be accessed.

This functions returns the authorization protocol name string that was
transmitted to the server during connection setup during the call to
open-display.  The authorization name indicates what authorization protocol
the client expects the server to use.  Specification of valid authorization
mechanisms is not part of the core X protocol.  It is hoped that eventually
one authorization protocol will be agreed upon.  In the mean time, a server
that implements a different protocol than the client expects, or a server
that only implements the host-based mechanism, may simply ignore this
information.  If both name and data strings are empty, this is to be
interpreted as "no explicit authorization".


(DEFUN display-display (display)
  (DECLARE (TYPE display display)
           (VALUES display-number)
           (TYPE integer display-number)))

display The display structure which is to be accessed.

Returns the display number for the host that was passed in the called to
open-display.


2.3.3.  Bitmap-Format and Pixmap-Formats


(DEFUN display-bitmap-format (display)
  (DECLARE (TYPE display display)
           (VALUES bitmap-format?)
           (TYPE bitmap-format bitmap-format?)))

display The display structure which is to be accessed.

This function returns the bitmap-format structure that contains the bitmap
format information for the specified display.


(DEFUN display-pixmap-formats (display)
  (DECLARE (TYPE display display)
           (VALUES pixmap-formats)
           (TYPE list pixmap-formats)))

display The display structure which is to be accessed.

This function returns the list of pixmap formats that was returned from the
server during connection setup in a call to open-display.  This list
contains one entry for each depth value.  The entry describes the ZFormat
used to represent images of that depth.  An entry for a depth is included if
any screen supports that depth, and all screens supporting that depth must
support (only) that ZFormat for that depth.


2.3.4.  Byte-Order and Image-LSB-First-P


(DEFUN display-byte-order (display)
  (DECLARE (TYPE display display)
           (VALUES byte-order)
           (TYPE (MEMBER :lsbfirst :msbfirst) byte-order)))

display The display structure which is to be accessed.

Returns the byte order to be employed in communication with the server.  The
possible values are :lsbfirst which means values are transmitted least
significant byte first, and :msbfirst which means values are transmitted
most significant byte first.  Except where explicitly noted in the protocol,
all 16-bit and 32-bit quantities sent by the client must be transmitted with
this byte order, and all 16-bit and 32-bit quantities returned by the server
will be transmitted with this byte order.


(DEFUN display-image-lsb-first-p (display)
  (DECLARE (TYPE display display)
           (VALUES image-lsb-first?)
           (TYPE boolean image-lsb-first?)))

display The display structure which is to be accessed.

Although the server is in general responsible for byte swapping data to
match the client, images are always transmitted and received in formats
(including byte order) specified by the server.  Within images for each
scanline unit in XYFormat images (bitmaps) or for each pixel value in
ZFormat images, the leftmost bit in the image as displayed on the screen is
either the least or most significant bit in the unit.  This function returns
non-null if it the least significant bit, otherwise it returns NIL.


2.3.5.  Default-Screen, NScreens, and Roots


(DEFUN display-default-screen (display)
  (DECLARE (TYPE display display)
           (VALUES default-screen)
           (TYPE (OR NULL screen) default-screen)))

display The display structure which is to be accessed.

Returns the default screen specified in the argument to the open-display
function.  This function should be used to retrieve the screen in
applications that will use only a single screen.


(DEFUN display-nscreens (display)
  (DECLARE (TYPE display display)
           (VALUES number-of-screens)
           (TYPE card8 number-of-screens)))

display The display structure which is to be accessed.

This function returns the number of screens on this server.


(DEFUN display-roots (display)
  (DECLARE (TYPE display display)
           (VALUES roots)
           (TYPE (LIST screen) roots)))

display The display structure which is to be accessed.

This function returns a list of the screens structures available for the
server.


2.3.6.  Error-Handler


(DEFUN display-error-handler (display)
  (DECLARE (TYPE display display)
           (VALUES error-handler)
           (TYPE (OR  (FUNCTION (display error &rest key-vals))
              (SEQUENCE (FUNCTION (display error &rest key-vals))))
                 error-handler)))

Settable.

display The display structure whose error-handler element is to be accessed.

All errors (synchronous and asynchronous) are processed by calling an error
handler specified in the error-handler element of the display structure.  If
the value of this element is a sequence it is expected to contain a handler
function for each specific error.  The error code is used as an index into
the sequence to fetch the appropriate handler function.  If this element is
a function it is called for all errors.  Any results returned by the handler
are ignored, since it is assumed the handler either takes care of the error
completely, or else signals.  The arguments passed to the handler function
are the display object, a symbol naming the type of error, and a set of
keyword-value arguments pairs which vary depending on the type of error.
For all core errors, the keyword-value argument pairs are:

        :current-sequence       card16
        :major                  card8
        :minor                  card16
        :sequence               card16

For colormap, cursor, drawable, font, gcontext, id-choice, pixmap, and
window errors the keyword-value pairs are the core error pairs plus:

        :resource-id            card32

For :atom errors the keyword-value pairs are the core error pairs plus:

        :atom-id                card32

For :value errors the keyword-value pairs are the core error pairs plus:

        :value                  card32

2.3.7.  Error Conditions

CLX errors are usually displayed using the default error handler. However,
the user has the option of redefining the default error handler for any given
display. The user can do this by modifying  the display structure's
error-handler slot. The replacement must be an executable function whose
formal parameters match those of the default handler.


(DEFMACRO define-condition (name (base) &body &optional items)
  )

name    The name of the condition being defined.

base    The parent type of the condition; ex: resource-error.

items    An association list of condition related items; either (:documentation
    doc-string), (:conc-name symbol-or-string) or (:report exp).


Define-condition defines a new condition type called name, which is a subtype
of the parent-type, base.  Except as otherwise noted, the arguments are not
evaluated.  Items are of the form: (:documentation doc-string), (:conc-name
symbol-or-string) or (:report exp).  When using the :documentation item,
doc-string should be a string which describes the purpose of the condition
type or NIL.  If this option is omitted, NIL is assumed.  When using the
:conc-name item, symbol-or-string sets up automatic prefixing of the names of
slot accessors.  If no :conc-name option is specified, the name of the new
condition type is followed by a hyphen will be used instead.  Conc-name is
interned in the package which is current at the time that the define-condition
is processed.

The :report item option defines a function which describes the condition type.
If exp is a literal string, it is a shorthand for (Lambda (Condition stream)
(Write-String exp stream)) If exp is not a literal string, it must be a
suitable argument to the special form, Function.  The expression (FUNCTION
exp) will be evaluated in the current lexical environment.  It should return a
function of two arguments, a condition and a stream, which prints on the
stream a description of the condition.  The :report option is processed after
the new condition type has been defined, so use of the slot accessors within
the report function is permitted.  If this option is not specified,
information about how to report this type of condition will be inherited from
the PARENT-TYPE.  See the CLEH reference manual for further information
regarding define-condition.


For example, the condition request-error (which is used as a parent-type for
defining other conditions) is defined by using the function define-condition.
The condition request-error makes use of the parent-type x-error.  The list
(display error-key major minor sequence current-sequence) defines accessor
slots that are described in the CLEH documentation.  The items list contains
only the :report option.




(define-condition access-error (request-error))

An access-error can occur for several reasons: A client attempted to grab a
key/button combination already grabbed by another client.  A client attempted
to free a color map entry that it did not already allocate.  A client
attempted to store into a read-only color map entry.  A client attempted to
modify the access control list from other than the local (or otherwise
authorized) host.  A client attempted to select an event type that another
client has already selected, and, that at most, one client can select at a
time.


(define-condition alloc-error (request-error))

The server failed to allocate the requested resource or server memory.


(define-condition atom-error (request-error)
  atom-id)

A value for an Atom argument does not name a defined Atom.


(define-condition closed-display (x-error)
  display)

The closed-display condition is signaled when trying to read or write a closed
display (i.e.  close-display has been called on the display object, or a
server-disconnect occurred).


(define-condition colormap-error (resource-error))

A value for a Colormap argument does not name a defined Colormap.


(define-condition connection-failure (x-error)
  (major-version
   minor-version
   host
   display
   reason))

Signaled when an X11 server refuses a connection.


(define-condition cursor-error (resource-error))

A value for a Cursor argument does not name a defined Cursor.

(define-condition device-busy (x-error)
  display)

Signaled by (setf (pointer-mapping display) mapping) when the
Set-Pointer-Mapping request returns a busy status.  A similar condition occurs
in set-modifier-mapping, but in this case, it returns a boolean indicating
success, rather than signaling an error.


(define-condition drawable-error (resource-error))

A value for a Drawable argument does not name a defined Window or Pixmap.


(define-condition font-error (resource-error))

A value for a Font or GContext argument does not name a defined Font.


(define-condition gcontext-error (resource-error))

A value for a GContext argument does not name a defined GContext.


(define-condition id-choice-error (resource-error))

The value chosen for a resource identifier is either not included in the range
assigned to the client or is already in use.  Under normal circumstances this
cannot occur and should be considered a server or CLX Library error.


(define-condition implementation-error (request-error))

The server does not implement some aspect of the request.  A server that
generates this error for a core request is deficient.  As such, this error is
not listed for any of the requests.  However, clients should be prepared to
receive such errors and either handle or discard them.


(define-condition length-error (request-error))

The length of a request is shorter or longer than that minimally required to
contain the arguments.  This usually means an internal CLX error.


(define-condition lookup-error (x-error)
  (id display type object)

CLX has the option of caching different resource types (see
*clx-cached-types*) in a hash table by resource-id.  When looking up an object
in the hash table, if the type of the object is wrong, a lookup-error is
signaled.  For example: The cursor with id 123 is interned in the hash table.
An event is received with a field for window 123.  When 123 is looked up in
the hash table, a cursor is found.  Since a window was expected, a
lookup-error is signaled.  This error should never occur unless buggy
extension code is being used.


(define-condition match-error (request-error))

In a graphics request, the root and depth of the GContext does not match that
of the drawable.  An input-only window is used as a Drawable.  Some argument
or pair of arguments has the correct type and range but fails to match in some
other way required by the request.  An input-only window locks this attribute.
The values do not exist for an input-only window.

(define-condition missing-parameter (x-error)
  parameter)

One or more of the required keyword parameter(s) is missing or NIL.


(define-condition name-error (request-error))

A font or color of the specified name does not exist.


(define-condition pixmap-error (resource-error))

A value for a Pixmap argument does not name a defined Pixmap.


(define-condition reply-length-error (x-error)
  (reply-length
   expected-length
   display))

The reply to a request has an unexpected length.


(define-condition reply-timeout (x-error)
  (timeout
   display))

The *reply-timeout* parameter specifies the maximum number of seconds to wait
for a request reply, or NIL to wait forever (the default).  When a reply
hasn't been received after *reply-timeout* seconds, the reply-timeout
condition is signaled.


(define-condition request-error (x-error)
  (display
   error-key
   major
   minor
   sequence
   current-sequence))

The major or minor opcode does not specify a valid request.


(define-condition resource-error (request-error)
  (resource-id))

Conditions are built in a hierarchy.  All CLX errors are built on top of the
x-error condition.  (what x-error is built on is implementation dependent, but
it's probably based on the ERROR condition.) resource-error is built on top of
x-error.  All X11 errors for incorrect resource id's are built on top of
resource-error.  These are colormap-error, cursor-error, drawable-error,
font-error, gcontext-error, id-choice-error, pixmap-error and window-error.
resource-error is never signaled directly.


(define-condition sequence-error (x-error)
  (display
   req-sequence
   msg-sequence))

All X11 request replies contain the sequence number of their request.  If a
replies sequence doesn't match the request count, a sequence-error is
signaled.  Sequence-error's usually indicate a locking problem with a
multi-processing lisp.


(define-condition server-disconnect (x-error)
  (display))

The connection to the server was lost.


(define-condition unexpected-reply (x-error)
  (display
   msg-sequence
   req-sequence
   length))

A reply was found when none was expected.  This should only occur when using
buggy extension code.


(define-condition unknown-error (request-error)
  (error-code))

An error was received from the server with an unknown error code.  This is
most probably caused by buggy extension code.

(define-condition value-error (request-error)
  (value))

Some numeric value falls outside the range of values accepted by the request.
Unless a specific range is specified for an argument, the full range defined
by the argument's type is accepted.  Any argument defined as a set of
alternatives can generate this error.

(define-condition window-error resource-error)

A value for a Window argument does not name a defined Window.


2.3.8.  Keycode-Range, Max-Keycode, and Min-Keycode


(DEFUN display-keycode-range (display)
  (DECLARE (TYPE display display)
           (VALUES min-keycode max-keycode)
           (TYPE card8 min-keycode max-keycode)))

display The display structure which is to be accessed.

Returns display-min-keycode and display-max-keycode as multiple values.


(DEFUN display-max-keycode (display)
  (DECLARE (TYPE display display)
           (VALUES max-keycode)
           (TYPE card8 max-keycode)))

display The display structure which is to be accessed.

This function returns the maximum keycode value transmitted by the server.
This value is never greater than 255.  Not all keycodes in the allowed range
are required to have corresponding keys.


(DEFUN display-min-keycode (display)
  (DECLARE (TYPE display display)
           (VALUES min-keycode)
           (TYPE card8 min-keycode)))

display The display structure which is to be accessed.

This function returns the minimum keycode value transmitted by the server.
This value is never less than 8.  Not all keycodes in the allowed range are
required to have corresponding keys.


2.3.9.  Max-Request-Length, Motion-Buffer-Size, and Squish


(DEFUN display-max-request-length (display)
  (DECLARE (TYPE display display)
           (VALUES max-request-length)
           (TYPE card16 max-request-length)))

display The display structure which is to be accessed.

This function returns the maximum length of a request, in 4-byte units, that
is accepted by the server.  Requests larger than this generate a length
error, and the server will read and simply discard the entire request.  This
length will always be at least 4096 (i.e., requests of length up to and
including 16384 bytes will be accepted by all servers).


(DEFUN display-motion-buffer-size (display)
  (DECLARE (TYPE display display)
           (VALUES motion-buffer-size)
           (TYPE card32 motion-buffer-size)))

display The display structure which is to be accessed.

This function returns the approximate size of motion buffer in the server.
The server may retain the recent history of pointer motion, and to a finer
granularity than is reported by motion-notify events.  Such history is
available via the motion-events function.


(DEFUN display-squish (display)
  (DECLARE (TYPE display display)
           (VALUES squish-mouse-move-event?)
           (TYPE boolean squish-mouse-move-event?)))

display The display structure which is to be accessed.

This function returns non-null if this server squishes mouse-moved events,
otherwise it returns NIL.


2.3.10.  Plist


(DEFUN display-plist (display)
  (DECLARE (TYPE display display)
           (VALUES plist)
           (TYPE list plist))))

display The display structure which is to be accessed.

This returns the property list for the specified display.  This is a hook for
extensions to hang data on.


2.3.11.  Protocol-Major-Version, Protocol-Minor-Version, Protocol-Version,
         Release-Number, Vendor, Vendor-Name, and Version-Number


(DEFUN display-protocol-major-version (display)
  (DECLARE (TYPE display display)
           (VALUES protocol-major-version)
           (TYPE card16 protocol-major-version)))

display The display structure which is to be accessed.

Returns the major version number of the X protocol associated with the X
server.  In general, the major version would increment for incompatible
changes.  The protocol version number returned indicate the protocol the
server actually supports.  This might not equal the version supported by the
client.  The server can (but need not) refuse connections from clients that
offer a different version than the server supports.  A server can (but need
not) support more than one version simultaneously.


(DEFUN display-protocol-minor-version (display)
  (DECLARE (TYPE display display)
           (VALUES protocol-minor-version)
           (TYPE card16 protocol-minor-version)))

display The display structure which is to be accessed.

Returns the minor protocol revision number associated with the X server.  In
general, the minor version would increment for small upward compatible changes
in the X protocol.


(DEFUN display-protocol-version (display)
  (DECLARE (TYPE display display)
           (VALUES protocol-major-version protocol-minor-version)
           (TYPE card16 protocol-major-version protocol-minor-version)))

display The display structure which is to be accessed.

Returns display-protocol-major-version and display-protocol-minor-version as
multiple values.


(DEFUN display-release-number (display)
  (DECLARE (TYPE display display)
           (VALUES release-number)
           (TYPE card32 release-number)))

display The display structure which is to be accessed.

Return a number related to a vendor's release of the X server.  The
semantics of the release-number is controlled by the vendor.


(DEFUN display-vendor (display)
  (DECLARE (TYPE display display)
           (VALUES vendor-name release-number)
           (TYPE string vendor-name)
           (TYPE card32 release-number)))

display The display structure which is to be accessed.

Returns display-vendor-name and display-release-number as multiple values.


(DEFUN display-vendor-name (display)
  (DECLARE (TYPE display display)
           (VALUES vendor-name)
           (TYPE string vendor-name)))

display The display structure which is to be accessed.

Return a string that provides some identification of the vendor of the X
server implementation.


(DEFUN display-version-number (display)
  (DECLARE (TYPE display display)
           (VALUES version-number)
           (TYPE card16 version-number)))

display The display structure which is to be accessed.

This function returns the X protocol version number for this implementation
of CLX.


2.3.11.  Resource-ID-Base, Resource-ID-Mask, and XID


(DEFUN display-resource-id-base (display)
  (DECLARE (TYPE display display)
           (VALUES resource-id-base)
           (TYPE resource-id resource-id-base)))

display The display structure which is to be accessed.

This function returns the resource id base value that was returned from the
server during connection setup in a call to open-display.  This is used in
combination with the resource id mask to construct valid ids for this
connection.


(DEFUN display-resource-id-mask (display)
  (DECLARE (TYPE display display)
           (VALUES resource-id-mask)
           (TYPE resource-id resource-id-mask)))

display The display structure which is to be accessed.

This function returns the resource id mask that was returned from the server
during connection setup in a call to open-display.  The resource id mask
contains a single contiguous set of bits (at least 18) which the client uses
to allocate resource ids for types window, pixmap, cursor, font, gcontext,
and colormap by choosing a value with (only) some subset of these bits set,
and oring it with the resource id base.  Only values constructed in this way
can be used to name newly created resources over this connection.  Resource
ids never have the top 3 bits set.  The client is not restricted to linear
or contiguous allocation of resource ids.  Once an id has been freed, it can
be reused, but this should not be necessary.  An id must be unique with
respect to the ids of all other resources, not just other resources of the
same type.  However, note that the value spaces of resource identifiers,
atoms, visualids, and keysyms are distinguished by context, and as such are
not required to be disjoint (e.g., a given numeric value might be both a
valid window id, a valid atom, and a valid keysym.)


(DEFUN display-xid (display)
  (DECLARE (TYPE display display)
           (VALUES resource-allocator)
           (TYPE #'function resource-allocator)))

display The display structure which is to be accessed.

This function returns the function that is used to allocate resource ids for
this display.


2.3.12.  XDefaults


(DEFUN display-xdefaults (display)
  (DECLARE (TYPE display display)
           (VALUES x-defaults)
           (TYPE ?? x-defaults)))

display The display structure which is to be accessed.

This function returns the contents of the defaults from the server.  This
provides a simple interface for clients not wishing to use a toolkit or the
more elaborate interfaces provided by the resource manager.  The data
returned by display-xdefaults are owned by CLX and should not be modified or
freed by the client.


2.4.  Closing the Display

To close or disconnect a display from the X server, use close-display.


(DEFUN close-display (display)
  (DECLARE (TYPE display display)))

display The display structure which is to be accessed.

This function closes the connection to the X server for the specified
display.  It destroys all windows, resource ids (window, font, pixmap,
colormap, cursor, and gcontext), and other resources (gcontexts) that the
client application has created on this display, unless the close down mode of
the resource has been changed (see set-close-down-mode).  Therefore, these
windows, resource ids, and other resources should never be referenced again.
In addition, this function discards any output requests that have been
buffered but have not yet been sent.


2.5.  X Server Connection Close Operations

When the X servers connection to a client is closed, either by an explicit
call to close-display or by some indirect effect, the X server performs
these automatic operations:

o    All selections (see set-selection-owner) owned by the client are
     disowned.

o    Performs an ungrab-pointer and ungrab-keyboard if the client
     application has actively grabbed the pointer or the keyboard.

o    Performs an ungrab-server if the client has grabbed the server.

o    Releases all passive grabs made by the client application.

o    Marks all resources (including colormap entries) allocated by the
     client application either as permanent or temporary, depending on
     whether the close-down mode argument is either :retain-permanent or
     :retain-temporary.  However, this does not prevent other client
     applications from explicitly destroying the resources.

When the close-down mode is :destroy, the X server destroys all of a client
application's resources as follows:

o    Examines each window in the client's save-set to determine if it is an
     inferior (subwindow) of a window created by the client.  (The save-set
     is a list of other clients windows, and windows in this list are
     referred to as a save-set window.) If so, the X server reparents the
     save-set window to the closest ancestor such that the save-set window
     is not an inferior of a window created by the client.

o    Performs a map-window on the save-set window if the save-set window is
     unmapped.  The X server does this even if the save-set window was not
     an inferior of a window created by the client.

o    Examines each window in the client's save-set, and destroys all windows
     created by the client.

o    Performs the appropriate free request on each non-window resource
     created by the client in the server (for example, font, pixmap, cursor,
     colormap, and gcontext).

o    Frees all colors and colormap entries allocated by a client
     application.

Additional processing occurs when the last connection to the X server
closes.  An X server goes through a cycle of having no connections and
having some connections.  When the last connection to the X server closes as
a result of a connection closing with the close-down mode of :destroy (that
is, the X server reverts to the state of having no connections), the X
server:

o    Resets its state, as if it had just been started.  The X server begins
     by destroying all lingering resources from clients that have terminated
     in :retain-permanent or :retain-temporary mode.

o    Deletes all but the predefined atom identifiers.

o    Deletes all properties on all root windows.

o    Resets all device maps and attributes (for example, key click, bell
     volume, and acceleration) and the access control list.

o    Restores the standard root tiles and cursors.

o    Restores the default font path.

o    Restores the input focus to state :pointer-root.

However, the X server does not reset if you close a connection with a
close-down mode of :retain-permanent or :retain-temporary.



                                  Chapter 3

                                   Screens


3.1.  Screen Functions

The following lists the Common LISP language functions and what data they
return for the specified screen structure.


(DEFUN screen-p (screen)
  (DECLARE (TYPE T screen)
           (VALUES screen?)
           (TYPE boolean screen?)))

screen  The screen structure which is to be accessed.

This function returns non-null if the screen argument is a screen structure,
otherwise it returns NIL.


3.2.  Screen Attributes


On some high resolution displays, it is possible to deal with color resources
in more than one way.  For example, you may be able to deal with a display as
either a 12-bit display with arbitrary "pixel to color" mapping (pseudo-color)
or as a 24-bit display with 8-bits of each 24-bit pixels dedicated for each
(true) color: red, green, and blue.  Different implementations of these visual
aspects of a display are called Visuals.


Many professional and/or personal computing work stations make use of a single
display processing unit coupled with a single screen and a dedicated memory
map.  The X philosophy is rather different in this respect.  In X, as well as
in CLX, each client can have multiple displays.  Each display can be of a
different visual type and different visual types can be supported at various
depths of the display's screen.  This allows for windows (including default
windows) with (possibly) different visual types to be defined for each screen.


The following concepts may serve to make the explanation of Visual
types clearer.  The screen can be color or gray scale.  The screen can have a
colormap that is writable or read-only.  A screen can also have a colormap
whose indices are decomposed into separate RGB pieces, provided one is not on a
gray scale screen.  This leads to the following diagram:


                       +-----------------+-----------------+
                       |      Color      |    Grayscale    |
                       +--------+--------+-----------------+
                       |  R/O   |  R/W   |  R/O   |  R/W   |
        +--------------+--------+--------+--------+--------+
        | Undecomposed | Static | Pseudo | Static |  Gray  |
        |   Colormap   | Color  | Color  |  Gray  | Scale  |
        +--------------+--------+--------+--------+--------+
        |  Decomposed  | True   | Direct |
        |   Colormap   | Color  | Color  |
        +--------------+--------+--------+


CLX uses a visual-info structure which contains information about the
potential color mapping.  The elements of this structure are the visual's: id,
class, red-mask, green-mask, blue-mask, bits-per-rgb, and colormap-entries.


(DEFSTRUCT visual-info
  (ID <unspec> :type card29)
  (CLASS <unspec> :type (MEMBER :static-gray :static-color :true-color
                                :gray-scale :pseudo-color :direct-color))
  (RED-MASK <unspec> :type pixel)
  (GREEN-MASK <unspec> :type pixel)
  (BLUE-MASK <unspec> :type pixel)
  (BITS-PER-RGB <unspec> :type card8)
  (COLORMAP-ENTRIES <unspec> :type card16))


id      A unique identification number.

Class   The class element specifies the possible visual classes of the screen.
        It can be one of the keywords --- :direct-color, :gray-scale,
        :pseudo-color, :static-color, :static-gray, or :true-color.

red-mask
green-mask
blue-mask
        The red-mask, green-mask, and blue-mask elements are only meaningful
        for the :direct-color and :true-color classes.  Each mask has one
        contiguous set of bits with no intersections.

bits-per-rgb
        The bits-per-rgb attribute specifies the log base 2 of the approximate
        number of distinct color values (individually) of red, green, and
        blue.  Actual RGB values are unsigned 16 bit numbers.

colormap-entries
        The colormap-entries attribute defines the number of available colormap
        entries in a newly created colormap.  For :direct-color and
        :true-color, this will be the size of an individual pixel subfield.


Conceptually, as each pixel is read out of memory, it goes through a lookup
stage by indexing into a colormap.  Colormaps can be manipulated arbitrarily
on some hardware, in limited way on other hardware, and not at all on yet
other hardware.  The various classes of visual types affect the colormap and
the RGB values in the following ways:

o    For :pseudo-color, a pixel value indexes a colormap to produce
     independent RGB values, and the RGB values can be changed dynamically.

o    The class :gray-scale is treated the same as :pseudo-color, except the
     primary which drives the screen is undefined.  Thus, the client should
     always store the same value for red, green, and blue in the colormaps.

o    For :direct-color, a pixel value is decomposed into separate RGB
     subfields, and each subfield separately indexes the colormap for the
     corresponding value.  The RGB values can be changed dynamically.

o    The class :true-color is treated the same as :direct-color, except the
     colormap has predefined read-only RGB values.  These RGB values are server
     dependent, but provide (near-)linear ramps in each primary.

o    The class :static-color is treated the same as :pseudo-color, except the
     colormap has predefined read-only server dependent RGB values.

o    The class :static-gray is treated the same as :static-color, except the
     red, green, and blue values are equal for any single pixel value, thus
     resulting in shades of gray.  Class :static-gray with a two entry colormap
     can be thought of as monochrome.


3.2.1.  Backing-Stores and Save-Unders-P


(DEFUN screen-backing-stores (screen)
  (DECLARE (TYPE screen screen)
           (VALUES backing-stores-type)
           (TYPE (MEMBER :always :never :when-mapped) backing-stores-type)))

screen  The screen structure which is to be accessed.

Returns a value indicating when the screen supports backing stores, although
it may be storage limited in the number of windows it can support at once.
The value returned can be one of :always, :never, or :when-mapped.  If
screen-save-unders is non-null, then the server can support the save-under
mode in create-window and in changing window attributes, although again it
may be storage limited.


(DEFUN screen-save-unders-p (screen)
  (DECLARE (TYPE screen screen)
           (VALUES save-unders?)
           (TYPE boolean save-unders?)))

screen  The screen structure which is to be accessed.

Returns non-null if the screen supports save unders, otherwise it returns
NIL.


3.2.2.  Black-Pixel and White-Pixel


(DEFUN screen-black-pixel (screen)
  (DECLARE (TYPE screen screen)
           (VALUES black-pixel)
           (TYPE pixel black-pixel)))

screen  The screen structure which is to be accessed.

Returns the black pixel value for the specified screen.  The black pixel and
white pixel can be used in implementing a "monochrome" application.  These
pixel values are for permanently allocated entries in the default colormap.
The actual RGB values are settable on some screens and, in any case, may not
actually be "black" or "white".  The names are intended to convey the
expected relative intensity of the colors.


(DEFUN screen-white-pixel (screen)
  (DECLARE (TYPE screen screen)
           (VALUES white-pixel)
           (TYPE pixel white-pixel)))

screen  The screen structure which is to be accessed.

Returns the white pixel value for the specified screen.  The black pixel and
white pixel can be used in implementing a "monochrome" application.  These
pixel values are for permanently allocated entries in the default colormap.
The actual RGB values are settable on some screens and, in any case, may not
actually be "black" or "white".  The names are intended to convey the
expected relative intensity of the colors.


3.2.3.  Default-Colormap, Max-Installed-Maps, and Min-Installed-Maps


(DEFUN screen-default-colormap (screen)
  (DECLARE (TYPE screen screen)
           (VALUES default-colormap)
           (TYPE colormap default-colormap)))

screen  The screen structure which is to be accessed.

Returns the default colormap for the specified screen.  This is the one
initially associated with the root window.  Clients with minimal color
requirements creating windows of the same depth as the root may want to
allocate from this map by default.  Most routine allocations of color should
be made out of this colormap.


(DEFUN screen-max-installed-maps (screen)
  (DECLARE (TYPE screen screen)
           (VALUES max-installed-colormaps)
           (TYPE card16 max-installed-colormaps)))

screen  The screen structure which is to be accessed.

Returns the maximum number of colormaps supported by the specified screen.
This specifies the maximum number of colormaps that might possibly be
installed simultaneously (with install-colormap), depending on their
allocations.  Multiple static-visual colormaps with identical contents but
differing in resource id should be considered as a single map for the
purposes of this number.  For the typical case of a single hardware
colormap, this values will be one.


(DEFUN screen-min-installed-maps (screen)
  (DECLARE (TYPE screen screen)
           (VALUES min-installed-colormaps)
           (TYPE card16 min-installed-colormaps)))

screen  The screen structure which is to be accessed.

Returns the minimum number of colormaps supported by the specified screen.
This specifies the number of maps that can be guaranteed to be installed
simultaneously (with install-colormap), regardless of the number of entries
allocated in each map.  Multiple static-visual colormaps with identical
contents but differing in resource id should be considered as a single map
for the purposes of this number.  For the typical case of a single hardware
colormap, this values will be one.


3.2.4.  Depths


(DEFUN screen-depths (screen)
  (DECLARE (TYPE screen screen)
           (VALUES depths)
           (TYPE (alist (image-depth depth) ((LIST visual-info) visuals))
                 depths)))

screen  The screen structure which is to be accessed.

The function returns an association list that specifies what pixmap and
window depths are supported on the specified screen.  Pixmaps are supported
for each depth listed, and windows of that depth are supported if at least
one visual type is listed for the depth.  A pixmap depth of one is always
supported and listed, but windows of depth one might not be supported.  A
depth of zero is never listed, but zero-depth input only windows are always
supported.


3.2.5.  Event-Mask-At-Open


(DEFUN screen-event-mask-at-open (screen)
  (DECLARE (TYPE screen screen)
           (VALUES event-mask-at-open)
           (TYPE mask32 event-mask-at-open)))

screen  The screen structure which is to be accessed.

Returns the initial root event mask for the specified screen.


3.2.6.  Height, Height-In-Millimeters, Width, and Width-In-Millimeters


(DEFUN screen-height (screen)
  (DECLARE (TYPE screen screen)
           (VALUES height)
           (TYPE card16 height)))

screen  The screen structure which is to be accessed.

Returns the height of the specified screen in pixel units.


(DEFUN screen-height-in-millimeters (screen)
  (DECLARE (TYPE screen screen)
           (VALUES height-in-millimeters)
           (TYPE card16 height-in-millimeters)))

screen  The screen structure which is to be accessed.

Returns the height of the specified screen in millimeters.  This can be used
with the width in millimeters to determine the physical size and the aspect
ratio of the screen.


(DEFUN screen-width (screen)
  (DECLARE (TYPE screen screen)
           (VALUES width)
           (TYPE card16 width)))

screen  The screen structure which is to be accessed.

Returns the width of the specified screen in pixel units.


(DEFUN screen-width-in-millimeters (screen)
  (DECLARE (TYPE screen screen)
           (VALUES width-in-millimeters)
           (TYPE card16 width-in-millimeters)))

screen  The screen structure which is to be accessed.

Returns the width of the specified screen in millimeters.  This can be used
with the height in millimeters to determine the physical size and the aspect
ratio of the screen.


3.2.7.  Plist


(DEFUN screen-plist (screen)
  (DECLARE (TYPE screen screen)
           (VALUES plist)
           (TYPE LIST plist)))

screen  The screen structure which is to be accessed.

This returns the property list for the specified screen.  This is a hook for
extensions to hang data on.


3.2.8.  Root, Root-Depth, and Root-Visual


(DEFUN screen-root (screen)
  (DECLARE (TYPE screen screen)
           (VALUES root-window)
           (TYPE (OR NULL window) root-window)))

screen  The screen structure which is to be accessed.

Returns the root window for the specified screen.  This function is useful
with functions that take a parent window as an argument.  The class of the
root window is always input output.


(DEFUN screen-root-depth (screen)
  (DECLARE (TYPE screen screen)
           (VALUES root-window-depth)
           (TYPE image-depth root-window-depth)))

screen  The screen structure which is to be accessed.

Returns the depth (number of planes) of the root window for the specified
screen.  Other depths may also be supported on this screen.


(DEFUN screen-root-visual (screen)
  (DECLARE (TYPE screen screen)
           (VALUES root-window-visual)
           (TYPE card29 root-window-visual)))

screen  The screen structure which is to be accessed.

Returns the default visual type for the root window for the specified
screen.



                                  Chapter 4

                                   Windows


In the X window system, a window is a rectangular area on the screen that
lets you view graphical output.  Client applications can display overlapping
and nested windows on one or more screens that are driven by X servers on
one or more machines.  Clients who want to create windows must first connect
their program to the X server by calling the CLX function open-display.
This chapter begins with a discussion of visual types and window attributes.
The chapter continues with a discussion of the CLX functions you can use to:

o    Create windows

o    Obtain information about a window

o    Configure windows

o    Change window attributes

o    Change the stacking order

o    Examine the window hierarchy

o    Translating window coordinates

o    Map windows

o    Unmap windows

o    Destroy windows

Note that it is vital that your application conform to the established
conventions for communicating with window managers for it to work well with
the various window managers in use.  Toolkits generally adhere to these
conventions for you, relieving you of the burden.  Toolkits also often
supersede many routines in this chapter with versions of their own.  You
should see the documentation for the toolkit you are using for more
information.


4.1.  Creating Windows

CLX provides basic ways of creating windows.  If you create your own top
level windows (direct children of the root window) the rules enumerated
below must be observed for applications to interact reasonably across
differing styles of window management.

You should never fight with a window manager for size or placement of your
top level window(s).  Toolkits often supply routines specifically for
creating and placing top level windows.  If you do not use a toolkit, you
should provide some standard information or "hints" to the window manager by
using the utility functions described in Chapter ??.

The policy guidelines for window creation are:

o    An application, by listening to the first exposure event, must be able
     to deal with whatever size window it gets, even if this means that the
     application just prints a message, like "Please make me bigger" in its
     window.

o    An application should only attempt to resize or move its top level
     window in direct response to a user request.  An application is free to
     resize or move the children of its top level window as necessary.
     (Toolkits often have facilities for automatic re-layout.) If a request
     to change the size of its top level window fails, the application must
     not fight with the window manager.

o    If an application does not use a toolkit that automatically sets
     standard window properties, that application should set these
     properties for the top level window before mapping it.  See Chapter ??
     for further information.

The low-level function provided by CLX to create an unmapped subwindow for a
specified parent window is create-window.  Create-window is a general
function that allows you to set specific window attributes when you create
it.

The X server acts as if input-only windows do not exist for the purposes of
graphics requests, exposure processing, and :visibility-notify events.  An
input-only window cannot be used as a drawable (that is, as a source or
destination for graphics requests).  In other respects input-only and
input-output windows act identically (properties, grabs, input control, and
so on).  Extension packages may define other classes of windows.


(DEFUN create-window (&key parent x y width height (depth 0)
                           (border-width 0) (class :copy) (visual :copy)
                           background border gravity bit-gravity
                           backing-store backing-planes backing-pixel
                           save-under event-mask do-not-propagate-mask
                           override-redirect colormap cursor)
  (DECLARE (TYPE window :parent)
           (TYPE int16 :x :y)
           (TYPE card16 :width :height :depth :border-width)
           (TYPE (MEMBER :copy :input-output :input-only) :class)
           (TYPE (OR (MEMBER :copy) visual) :visual)
           (TYPE (OR NULL (MEMBER :none :parent-relative) pixel pixmap)
                 :background)
           (TYPE (OR NULL (MEMBER :copy) pixel pixmap) :border)
           (TYPE (OR NULL win-gravity) :gravity)
           (TYPE (OR NULL bit-gravity) :bit-gravity)
           (TYPE (OR NULL (MEMBER :not-useful :when-mapped :always)
                     backing-store) :backing-store)
           (TYPE (OR NULL pixel) :backing-planes :backing-pixel)
           (TYPE (OR NULL event-mask) :event-mask)
           (TYPE (OR NULL device-event-mask) :do-not-propagate-mask)
           (TYPE (OR NULL (MEMBER :on :off)) :save-under :override-redirect)
           (TYPE (OR NULL (MEMBER :copy) colormap) :colormap)
           (TYPE (OR NULL (MEMBER :none) cursor) :cursor)
           (VALUES window-structure)
           (TYPE window window-structure)))

:parent A required keyword argument that specifies the parent for the window
        which is to be created.

:x
:y      Required keyword arguments which specify the x and y coordinates for
        the top, left, outside corner of the borders for the window which is
        being created.  These coordinates are relative to the inside of the
        parent window's borders.

:width
:height Required keyword arguments which specify the inside dimensions, in
        pixels, of the window which is being created.  These dimensions do
        not include the window borders and must be greater than zero.

:depth  A depth of zero for class :input-output or :copy means the depth is
        taken from the parent.

:border-width
        Specifies, in pixels, the width of the created window's border.  The
        border-width for an input-only window must be zero.

:class  Specifies the created window's class.  A class of :copy means the
        class is taken from the parent.

:visual Specifies the visual type.  A visual of :copy means the visual type
        is taken from the parent.

:background
:border
:gravity
:bit-gravity
:backing-store
:backing-planes
:backing-pixel
:save-under
:event-mask
:do-not-propagate-mask
:override-redirect
:colormap
:cursor Specifies the attributes of the window which are to be set at
        creation time.  Only the non-null attributes are passed on in the
        request and no assumption is made about what the actual protocol
        defaults are.  See Section 4.4 for further information on window
        attributes.

The create-window function creates an unmapped subwindow for a specified
parent window, returns the window structure for the created window, and
causes the X server to generate a :create-notify event.  The created window
is placed on top in the stacking order with respect to siblings.

For the input-output class of windows, the visual type and depth must be a
combination supported for the screen.  The depth need not be the same as the
parent, but the parent must not be a window of class input-only.

For an input-only window the depth must be zero, and the visual must be one
supported by the screen.  The parent window, however, may have any depth and
class.  The only window attributes defined for input-only windows are
gravity, event-mask, do-not-propagate-mask, override-redirect, and cursor.

A window manager may override your choice as to size, border-width, and
position for a window when it is first mapped.  Your program must be
prepared to use the actual size and position of the top window, which is
reported back.  It is not acceptable for a client application to resize
itself unless in direct response to a human command to do so.  Instead, your
program should either use the space given to it, or, if the space is too
small for any useful work, your program might ask the user to resize the
window.  The border of your top level windows are considered fair game for
window managers.


4.2.  Obtaining Information About a Window

CLX provides a number of useful functions that return data from a window
structure.  All other elements (that is, those for which no functions are
defined) are internal to CLX and must not be used.  The following lists the
Common LISP language functions and what data they return for the specified
window structure.


(DEFUN window-class (window)
  (DECLARE (TYPE window window)
           (VALUES class)
           (TYPE (MEMBER :input-only :input-output) class)))

window  The window structure which is to be accessed.

This function returns the class of the specified window object.  The only
two classes supported in the core protocol are :input-only and :input-output
but extension packages may define other classes of windows.  The X server
acts as if input-only windows do not exist for the purposes of graphics
requests, exposure processing, and visibility-notify events.  An input-only
window cannot be used as a drawable (that is, as a source or destination for
graphics requests).  In other respects input-only and input-output windows
act identically (properties, grabs, input control, and so on).


(DEFUN window-equal (window-1 window-2)
  (DECLARE (TYPE window window-1 window-2)
           (VALUES equal?)
           (TYPE boolean equal?)))

window-1
window-2
        The window structures which are to be compared for equality.

This function returns non-null if the two arguments are the same windows and
NIL if they are not.


(DEFUN window-id (window)
  (DECLARE (TYPE window window)
           (VALUES id)
           (TYPE resource-id id)))

window  The window structure which is to be accessed.

This function returns the unique id that has been assigned to the specified
window by the server.


(DEFUN window-p (window)
  (DECLARE (TYPE T window)
           (VALUES window?)
           (TYPE boolean window?)))

window  The window structure which is to be accessed.

This function returns non-null if the window argument is a window structure,
otherwise it returns NIL.


(DEFUN window-plist (window)
  (DECLARE (TYPE window window)
           (VALUES plist)
           (TYPE list plist))))

window  The window structure which is to be accessed.

This returns the property list for the specified window.  This is a hook for
extensions to hang data on.


(DEFUN window-visual (window)
  (DECLARE (TYPE window window)
           (VALUES visual-type)
           (TYPE card29 visual-type)))

window  The window structure which is to be accessed.

This function returns the visual type associated with the specified window.


4.3.  Window Configuration

All drawables have a border-width, an x and y position, a width, a height,
and a depth (collectively referred to as the geometry).  In addition, windows
have a stacking priority.  The border-width element specifies the width of
the border in pixels.  The x and y elements specify the x and y coordinates
relative to the parent's origin and indicate the position of the upper,
left, outer corner for a window.  The width and height elements specify the
inside size of the drawable, in pixels, not including the border.  Depth is
the number of bits per pixel for the drawable.  The stacking priority
element specifies the priority of a window, relative to its siblings, for
stacking operations.

For the input-only class of windows the border-width is always zero.  For
pixmaps x, y, and border-width will always be zero.

CLX provides functions with which you can obtain information about and
change a drawables configuration.  The configuration includes the
information that describes the geometry of the a drawable.  Modifying the
configuration is how you move a window, resize a window, modify the depth of
a window, change a window's border-width, or change a window's stacking
priority.  Attempts to change the configuration of a root window have no
effect and the elements of the configuration of pixmaps are not settable.

When the geometry of a window is changed, the window is restacked among
siblings, the restack check is performed with respect to the window's final
size and position (NOT its initial position), and a configure-notify event
is generated if the state of the window actually changes.  The X server
generates gravity-notify events after generating configure-notify events.
Exposure processing is performed on formerly obscured windows, including the
window itself and its inferiors, if regions of them were obscured but now
are not.

The complete set of elements in the window configuration are discussed in
the following sections.


4.3.1.  Border-Width

The border-width specifies the width, in pixels, of the area on each of the
four sides of a window, that is occupied by the window border.  The value is
always zero or greater.  For pixmaps and input-only windows the border-width
is always zero.

Output to a window is always clipped to the inside of the window.
Therefore, graphic operations never affect the window border.  The border of
your top level windows are considered fair game for window managers.  Also,
the window manager may override the value for border-width and your program
must be prepared to deal with this.


(DEFUN drawable-border-width (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES border-width)
           (TYPE card16 border-width)))

drawable
        The drawable whose border-width is to be accessed.

Settable for windows only.

This function returns the border-width element of the specified drawable in
pixels.  It always returns zero if the drawable is a pixmap or an input-only
window.

Changing just the border-width leaves the outer-left corner of a window in a
fixed position, but moves the absolute position of the window's origin.  It
is an error to make the border-width of an input-only window non-zero.


4.3.2.  X and Y Position

The x and y position defines the location of the drawable.  For a window,
these coordinates specify the upper, left, outer corner relative to its
parent's origin.  For pixmaps, these coordinates are always zero.

A window manager may override your choice as to position for a window and
your program must be prepared to deal with this.

(DEFUN drawable-x (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES outside-left)
           (TYPE int16 outside-left)))

drawable
        The drawable whose x position is to be accessed.

Settable for windows only.


(DEFUN drawable-y (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES outside-top)
           (TYPE int16 outside-top)))

drawable
        The drawable whose y position is to be accessed.

Settable for windows only.

These functions return the x or y coordinate of the specified drawable.
They always returns zero if the drawable is a pixmap.  These coordinates
define the location of the top left pixel of the window's border or the
window itself, if it has no border.

Changing just the x and y coordinates is how you move a window without
changing its size.  Setting these values moves the window to the specified x
and y coordinates, but it does not change the window's size, does not raise
the window, and does not change the mapping state of the window.

Moving a mapped window may or may not lose its contents depending on:

o    If its background attribute has the value :parent-relative.

o    If the window is obscured by non-children, and no backing store exists.

If the contents of the window are lost, exposure events will be generated
for the window and any mapped subwindows.  Moving a mapped window will
generate exposure events on any formerly obscured windows.

When changing the position of a window, if the override-redirect attribute
of the window is :off and some other client has selected
substructure-redirect on the parent, a configure-request event is generated,
and no further processing is performed.  Otherwise, the window is moved.


4.3.3.  Width and Height

The width and height elements define the inside size, in pixels, of the
drawable, not including the border.  These values are always greater than
zero.

A window manager may override your choice as to size for a top level window
and your program must be prepared to deal with this.  Also, it is not
acceptable for a client application to resize itself unless in direct
response to a human command to do so.  Instead, your program should either
use the space given to it, or, if the space is too small for any useful
work, your program might ask the user to resize the window.


(DEFUN drawable-height (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES inside-height)
           (TYPE card16 inside-height)))

drawable
        The drawable whose height element is to be accessed.

Settable for windows only.


(DEFUN drawable-width (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES inside-width)
           (TYPE card16 inside-width)))

drawable
        The drawable whose width element is to be accessed.

Settable for windows only.

These functions return the height or width element of the specified
drawable.  These coordinates define the inside size of the drawable, in
pixels, or of the entire window, if it has no border.

Changing just the width and height is how you resize a window without
changing its position.  Setting these values changes the inside dimensions
of the window to the specified width and height, but it does not change the
position of the window's upper, left corner or its origin, does not raise
the window, and does not change the mapping state of the window.

Changing the size of a mapped window may lose its contents and generate an
expose event.  If a mapped window is made smaller, exposure events will be
generated on windows that it formerly obscured.

When changing the size of a window, if the override-redirect attribute of
the window is :off and some other client has selected substructure-redirect
on the parent, a configure-request event is generated, and no further
processing is performed.  Otherwise, if some other client has selected
resize-redirect on the window a resize-request event is generated, and the
current inside width and height are maintained.  Note that the
override-redirect attribute of the window has no effect on resize-redirect
and that substructure-redirect on the parent has precedence over
resize-redirect on the window.

When the inside size of the window is changed the children of the window may
move according to their window gravity.  Depending on the window's bit
gravity, the contents of the window also may be moved.  See Section 4.4.3
for further information.


4.3.4.  Depth

The depth of a drawable is the number of bits per pixel it has.  This depth
must be one of the depths that is supported by the screen for this drawable.
For an input-only window the depth is always zero.


(DEFUN drawable-depth (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES depth)
           (TYPE card8 depth)))

drawable
        The drawable whose width element is to be accessed.

This function returns the depth of the specified drawable (bits per pixel).


4.3.5.  Stacking Priority

The stacking priority element specifies the priority of a window, relative
to its siblings, for stacking operations.  Possible values are :above,
:below, :bottom-if, :opposite, or :top-if.

If a sibling window is specified, the window is restacked based on the mode
as follows:

:above          The window is placed just above the sibling.

:below          The window is placed just below the sibling.

:bottom-if      If the window occludes the sibling, the window is placed at
                the bottom of the stack.

:opposite       If the sibling occludes the window, the window is placed at
                the top of the stack.  Otherwise, if the window occludes the
                sibling, the window is placed at the bottom of the stack.

:top-if         If the sibling occludes the window, the window is placed at
                the top of the stack.

If no sibling is specified (value of NIL), the window is restacked based on
the mode as follows:

:above          The window is placed at the top of the stack.

:below          The window is placed at the bottom of the stack.

:bottom-if      If the window occludes any sibling, the window is placed at
                the bottom of the stack.

:opposite       If any sibling occludes the window, the window is placed at
                the top of the stack.  Otherwise, if the window occludes any
                sibling, the window is placed at the bottom of the stack.

:top-if         If any sibling occludes the window, the window is placed at
                the top of the stack.

The X protocol does not allow retrieval of the stacking priority value for a
window.  It is only settable.  In other words, it is a write only value.


(DEFSETF window-priority (window &optional sibling) (mode)
  (DECLARE (TYPE window window)
           (TYPE (OR NULL window) sibling)
           (TYPE (MEMBER :above :below :bottom-if :opposite :top-if) mode)
           (VALUES mode)
              (TYPE (MEMBER :above :below :bottom-if :opposite :top-if) mode)))

window  Specifies the window whose stacking priority is to be set.

sibling An optional argument specifying a sibling window which this window is
        to be restacked relative to.

mode    Specifies the new value for the stacking priority.  It may be
        :above, :below, :bottom-if, :opposite, or :top-if as described
        above.

This SETF operation changes the stacking priority element of the window to
the value specified.  It is an error if the sibling argument is not actually
a sibling of the window.


4.4.  Window Attributes

All windows have a border, an optional background, an input mask, an event
suppression mask, and a property list.  The window border and background can
be a solid color or a pattern, called a tile.  All windows except the root
have a parent and are clipped by their parent.  If a window is stacked on
top of another window, it obscures that other window for the purpose of
input.  If a window has a background (almost all do), it obscures the other
window for purposes of output.  Attempts to output to the obscured area will
do nothing, and no input events (for example, pointer motion) will be
generated for the obscured area.

The input-only class of windows only have the following attributes:

o    gravity

o    event-mask

o    do-not-propagate-mask

o    override-redirect

o    cursor

They are used for controlling input events in situations where full-fledged
windows are unnecessary.  An error is generated if you specify any other
attributes for an input-only window.

Windows have borders of a programmable width and pattern as well as a
background pattern or tile.  Pixels can be used for solid colors.  The
background and border pixmaps may be destroyed immediately after creating
the window if no further explicit references to them are to be made.

A window's background pattern can be either a solid color or a pattern.  The
pattern can either be relative to the parent or absolute.  If relative to
the parent, the pattern will be shifted appropriately to match the parent
window.  If absolute, the pattern will be positioned in the window
independently of the parent window.


(DEFMACRO with-state ((drawable) &body body))

drawable
        The drawable whose state is to be maintained.

The with-state macro allows a consistent view to be obtained and allows a
coherent update of the window attributes and window geometry.  The body is not
surrounded by a with-display.  Within the indefinite scope of the body, on a
per-process basis in a multi-process environment, the first call within an
Accessor Group on the specified drawable (the object, not just the variable)
causes the complete results of the protocol request to be retained, and
returned in any subsequent accessor calls.  Calls within a SETF Group are
delayed, and executed in a single request on exit from the body.  In addition,
if a call on a function within an Accessor Group follows a call on a function
in the corresponding SETF Group, then all delayed SETFs for that group are
executed, any retained accessor information for that group is discarded, the
corresponding protocol request is (re)issued, and the results are (again)
retained, and returned in any subsequent accessor calls.



The complete set of window attributes are discussed in the following sections.

4.4.1.  Background

The background attribute specifies a pixel value used to paint a window's
background in a single color or a pixmap to be used for a window's
background.  Possible values are any pixel value, a pixmap, :none, or
:parent-relative.  The default value is :none.

If the background attribute is a pixel, a pixmap of undefined size filled
with the pixel is used for the background.  If the background is a pixmap,
it overrides the default background.  A background pixmap can be of any size
(although some sizes may be faster than others) but the pixmap and the
window must have the same root and the same depth.  If the background
attribute is :none then the window has no defined background.  If you set
the background to :parent-relative:

o    The parent window's background is used, but the child window must have
     the same depth as its parent.  If the parent window has a background of
     :none, the window will also have a background of :none.

o    A copy of the parent window's background is not made.  The parent's
     background is examined each time the child window background is
     required.

o    The background tile origin always aligns with the parent window's
     background tile origin.  Otherwise, the background tile origin is
     always the child window origin.

Setting a new value for the background attribute overrides any previous
background.  If the value is a pixmap it can be freed immediately if no
further explicit reference is made to it (the X server will keep a copy to
use when needed).  If you later draw into the pixmap used for the
background, X does not predict what happens because the X implementation is
free to either make a copy of the pixmap or just use the same pixmap.

When no valid contents are available for regions of a window, and either the
regions are visible, or the server is maintaining backing store, the server
automatically tiles the regions with the window's background, unless the
window has a background of :none.  If the background is :none, the previous
screen contents are simply left in place, if the contents come from an
inferior window of the same depth.  Otherwise, the initial contents of the
exposed regions are undefined.  Exposure events are then generated for the
regions, even if the background is :none.  See Chapter ??  for a discussion
of exposure event processing.

The X protocol does not allow retrieval of the background attribute value
for a window.  It is only settable.  In other words, it is a write only
value.


(DEFSETF window-background (window) (background)
  (DECLARE (TYPE window window)
           (TYPE (OR (MEMBER :none :parent-relative) pixel pixmap)
                 background)
           (VALUES background)
           (TYPE (OR (MEMBER :none :parent-relative) pixel pixmap)
                 background)))

window  Specifies the window whose background attribute is to be set.

background
        Specifies the new value for background attribute.  It may be a pixel
        value, a pixmap, :none, or :parent-relative as described above.

This SETF operation changes the background attribute of the window to the
value specified.  This operation is not allowed on an input-only window.
Changing the background does not cause the window contents to be changed.
You may wish to clear and repaint the screen after executing this operation
because they will not repaint the background you just set.


4.4.2.  Border

The border attribute specifies a pixel value used to paint a window's border
in a single color or a pixmap to be used for a window's border.  Possible
values are any pixel value, a pixmap, or :copy.  The default value is :copy.

If the border attribute is a pixel, a pixmap of undefined size filled with
the pixel is used for the border.  If the border is a pixmap, it overrides
the default border.  A border pixmap can be of any size (although some sizes
may be faster than others) but the pixmap and the window must have the same
root and the same depth.  This pixmap can be of any size, although some
sizes may be faster than others.  The border tile origin is always the same
as the background tile origin.  If you set the border to :copy the pixmap
used for the border will be a copy of the parent window's border pixmap.
Subsequent changes to the parent window's border attribute do not affect the
child window.

Setting a new value for the border attribute overrides any previous border.
If the value is a pixmap it can be freed immediately if no further explicit
reference is made to it.  If you later draw into the pixmap used for the
border, X does not predict what happens because the X implementation is free
to either make a copy of the pixmap or use the same pixmap each time the
window border is repainted.

Output to a window is always clipped to the inside of the window.
Therefore, graphic operations never affect the window border.  Borders are
added to the window size specified.

The X protocol does not allow retrieval of the border attribute value for a
window.  It is only settable.  In other words, it is a write only value.


(DEFSETF window-border (window) (border)
  (DECLARE (TYPE window window)
           (TYPE (OR (MEMBER :copy) pixel pixmap) border)
           (VALUES border)
           (TYPE (OR (MEMBER :copy) pixel pixmap) border)))

window  Specifies the window whose border attribute is to be set.

border  Specifies the new value for border attribute.  It may be a pixel
        value, a pixmap, or :copy as described above.

This SETF operation changes the border attribute of the window to the value
specified.  This operation is not allowed on an input-only window.  Changing
the border attribute also causes the window border to be repainted.


4.4.3.  Bit Gravity and Window Gravity Attributes


(DEFTYPE bit-gravity () '(MEMBER :center :east :forget :north :north-east
                                 :north-west :south :south-east :south-west
                                 :static :west))

Bit gravity defines which region of the window should be retained when the
window is resized.  The default value for the bit-gravity attribute is
:forget.


(DEFTYPE win-gravity () '(MEMBER :center :east :north :north-east
                                 :north-west :south :south-east :south-west
                                 :static :unmap :west))

Window gravity allows you to define how the window should be repositioned if
its parent is resized.  The default value for the window gravity attribute
is :north-west.

If the inside width or height of a window is not changed, and if the window
is moved or its border is changed, then the contents of the window are not
lost but move with the window.  Changing the inside width or height of the
window causes its contents to be moved or lost, depending on the bit-gravity
of the window, and causes children to be reconfigured, depending on their
window gravity.  For a change of width and height, the (x, y) pairs are
defined as:

          -----------------------------------------
          Gravity Direction     Coordinates
          -----------------------------------------

          :center               (width/2, height/2)

          :east                 (width, height/2)

          :north                (width/2, 0)

          :north-east           (width, 0)

          :north-west           (0, 0)

          :south                (width/2, height)

          :south-east           (width, height)

          :south-west           (0, height)

          :west                 (0, height/2)
          -----------------------------------------

When a window having one of these bit-gravities is resized, the
corresponding (x, y) pair defines the change in position of each pixel in
the window.  When a window with one of these window gravities has its parent
window resized, the corresponding pair defines the change in position of the
window within the parent.  When a window is so repositioned, a
gravity-notify event is generated.  The gravity-notify events are generated
after the configure-notify event is generated.

A bit-gravity of :static indicates that the contents or origin should not
move relative to the origin of the root window.  If the change in size of
the window is coupled with a change in position (x, y), then for bit-gravity
the change in position of each pixel is (-x, -y), and for window gravity the
change in position of a child when its parent is so resized is (-x, -y).
Note that :static gravity still only takes effect when the width or height
of the window is changed, not when the window is moved.

A bit-gravity of :forget indicates that the window's contents are always
discarded after a size change, even if a backing-store or save-under has
been requested.  The window is tiled with its background and one or more
exposure events are generated.  If no background is defined, the existing
screen contents are not altered.  Some X servers may also ignore the
specified bit-gravity and always generate exposure events.

A window gravity of :unmap is like :north-west (the window is not moved),
but the child is also unmapped when the parent is resized, and an
:unmap-notify event is generated.  The unmap-notify events are generated
after the configure-notify event is generated.


(DEFUN window-bit-gravity (window)
  (DECLARE (TYPE window window)
           (VALUES bit-gravity?)
           (TYPE bit-gravity bit-gravity?)))

Settable.

window  Specifies the window whose bit-gravity attribute is to be accessed.

Returns the value of the bit-gravity attribute for the specified window.


(DEFUN window-gravity (window)
  (DECLARE (TYPE window window)
           (VALUES gravity)
           (TYPE win-gravity gravity)))

Settable.

window  Specifies the window whose window gravity attribute is to be
        accessed.

Returns the value of the window gravity attribute for the specified window.
Changing the window gravity does not affect the current position of the
window.


4.4.4.  Backing-Store

Some implementations of the X server may choose to maintain the contents of
windows.  If the X server maintains the contents of a window, the off-screen
saved pixels are known as backing store.  The backing-store attribute
advises the X server on what to do with the contents of a window.  Possible
values for this attribute are :always, :not-useful, and :when-mapped.  The
default value is :not-useful.

A backing-store of :when-mapped advises the X server that maintaining
contents of obscured regions when the window is mapped would be beneficial.
In this case, the server may generate an exposure event when the window is
created.  A backing-store of :always advises the X server that maintaining
contents even when the window is unmapped would be beneficial.  Even if the
window is larger than its parent, this is a request to the X server to
maintain complete contents, not just the region within the parent window
boundaries.  While the X server maintains contents, exposure events normally
will not be generated, but the X server may stop maintaining contents at any
time.  A backing-store of :not-useful advises the X server that maintaining
contents is unnecessary, although some X implementations may still choose to
maintain contents and, therefore, not generate exposure events.

When the contents of obscured regions of a window are being maintained,
regions obscured by non-inferior windows are included in the destination
(AND source, when the window is the source) of graphics requests.  However,
regions obscured by inferior windows are not included.


(DEFUN window-backing-store (window)
  (DECLARE (TYPE window window)
           (VALUES backing-store-type)
           (TYPE (MEMBER :always :not-useful :when-mapped)
                 backing-store-type)))

Settable.

window  Specifies the window whose backing-store attribute is to be
        accessed.

Returns the value of the backing-store attribute for the specified window.
Changing the backing-store attribute of an obscured window to :when-mapped
or :always may have no immediate effect.


4.4.5.  Save-Under

Some server implementations may preserve bits of windows under other
windows.  This is not the same as preserving the contents of a window.  You
may get better visual appeal if transient windows (for example, pop-up
menus) request that the system preserve the bits under them, so the
temporarily obscured applications do not have to repaint.

The default value for the save-under attribute is :off.  If save-under is
:on, the X server is advised that, when this window is mapped, saving the
contents of windows it obscures would be beneficial.


(DEFUN window-save-under (window)
  (DECLARE (TYPE window window)
           (VALUES save-under)
           (TYPE (MEMBER :on :off) save-under)))

Settable.

window  Specifies the window whose save-under attribute is to be accessed.

Returns the value of the save-under attribute for the specified window.
Changing the save-under attribute of a mapped window may have no immediate
effect.


4.4.6.  Backing-Planes and Backing-Pixel Attributes

The backing-planes attribute indicates (with one bits) which bit planes of
the window hold dynamic data that must be preserved in backing store and
during save unders.  The default value for the backing-planes attribute is
all ones.  The backing-pixel specifies what values to use in planes not
covered by backing-planes.  The default value for the backing-pixel
attribute is zero.  The X server is free to save only the specified bit
planes in the backing store or the save under and is free to regenerate the
remaining planes with the specified pixel value.  Any extraneous bits (that
is, those beyond the specified depth of the window) in these values may be
simply ignored.  If you request backing store or save unders you should use
these attributes to minimize the amount of off-screen memory required to
store your window.


(DEFUN window-backing-pixel (window)
  (DECLARE (TYPE window window)
           (VALUES backing-pixel)
           (TYPE pixel backing-pixel)))

Settable.

window  Specifies the window whose backing-pixel attribute is to be
        accessed.

Returns the value of the backing-pixel attribute for the specified window.
Changing the backing-pixel attribute of a mapped window may have no
immediate effect.


(DEFUN window-backing-planes (window)
  (DECLARE (TYPE window window)
           (VALUES backing-planes)
           (TYPE pixel backing-planes)))

Settable.

window  Specifies the window whose backing-planes attribute is to be
        accessed.

Returns the value of the backing-planes attribute for the specified window.
Changing the backing-planes attribute of a mapped window may have no
immediate effect.


4.4.7.  Event-Mask and Do-Not-Propagate-Mask Attributes

The event-mask defines which events the client is interested in for this
window (OR, for some event types, inferiors of the window).  The
do-not-propagate-mask defines which events should not be propagated to
ancestor windows when no client has the event type selected in this window.
These masks are the bitwise inclusive-or of one or more of the valid event
mask bits.  The default value for these attributes is the empty set.


Multiple clients can select input on the same window but their event-masks
are disjoint.  When an event is generated it will be reported to all
interested clients.  However, at most one client at a time can select
substructure redirect, at most one client at a time can select resize
redirect, and at most one client at a time can select button press.  There
is only one do-not-propagate-mask for a window, not one per client.


(DEFTYPE event-mask-class ()
  '(MEMBER :button-1-motion :button-2-motion :button-3-motion
           :button-4-motion :button-5-motion :button-motion :button-press
           :button-release :colormap-change :enter-window :exposure
           :focus-change :key-press :key-release :keymap-state :leave-window
           :owner-grab-button :pointer-motion :pointer-motion-hint
           :property-change :resize-redirect :structure-notify
           :substructure-notify :substructure-redirect :visibility-change))

The type event-mask-class is a keyword name which corresponds to a
particular bit in an event bitmask.


(DEFTYPE event-mask ()
  '(OR mask32 (LIST event-mask-class)))

The type event-mask is a way to specify a set of bits for an event bitmask.
Two ways of specifying the bits are allowed.  By setting the event bits in a
32 bit mask or by listing the keyword names of the event bits in a list.


(DEFTYPE pointer-event-mask-class ()
  '(MEMBER :button-1-motion :button-2-motion :button-3-motion
           :button-4-motion :button-5-motion :button-motion :button-press
           :button-release :enter-window :keymap-state :leave-window
           :pointer-motion :pointer-motion-hint))

The type pointer-event-mask-class is a keyword name, for a pointer related
event, which corresponds to a particular bit in an event bitmask.  The set
of names is a subset of the names in the type event-mask-class.


(DEFTYPE pointer-event-mask ()
  '(OR mask32 (LIST pointer-event-mask-class)))

The type pointer-event-mask is a way to specify a set of bits for an event
bitmask.  Two ways of specifying the bits are allowed.  By setting the event
bits in a 32 bit mask or by listing the keyword names of the pointer related
event bits in a list.


(DEFTYPE device-event-mask-class ()
  '(MEMBER :button-1-motion :button-2-motion :button-3-motion
           :button-4-motion :button-5-motion :button-motion :button-press
           :button-release :key-press :key-release :pointer-motion))

The type device-event-mask-class is a keyword name, for a device related
event, which corresponds to a particular bit in an event bitmask.  The set
of names is a subset of the names in the type event-mask-class.


(DEFTYPE device-event-mask ()
  '(OR mask32 (LIST device-event-mask-class)))

The type device-event-mask is a way to specify a set of bits for an event
bitmask.  Two ways of specifying the bits are allowed.  By setting the event
bits in a 32 bit mask or by listing the keyword names of the device related
event bits in a list.


(DEFUN window-all-event-masks (window)
  (DECLARE (TYPE window window)
           (VALUES all-event-masks)
           (TYPE mask32 all-event-masks)))

window  Specifies the window whose all-event-mask is to be returned.

This function returns the inclusive-OR of all event masks selected on the
specified window by clients.


(DEFUN make-event-mask (&rest keys)
  (DECLARE (TYPE (LIST event-mask-class) keys)
           (VALUES event-mask?)
           (TYPE mask32 event-mask?)))

keys    Keyword names for the event bits which are to be set in the event
        bitmask that is returned.

This function is useful for constructing an event mask from a set of keyword
names for the event bits.  This is only defined to work for core events.  An
event bitmask with the specified bits set is returned.


(DEFUN make-event-keys (event-mask)
  (DECLARE (TYPE mask32 event-mask)
           (VALUES event-keywords)
           (TYPE (LIST event-mask-class) event-keywords)))

event-mask
        Event bitmask which is to be decoded.

This function returns a list of keyword names for the event bits that are
set in the specified event bitmask.  This is only defined to work for core
events.


(DEFUN make-state-mask (&REST keys)
  (DECLARE (TYPE (LIST state-mask-key) keys)
       (VALUES mask)
           (TYPE mask16 mask))

Keys    is a list of keys that are to turned into 16-bit masks.

The make-state-mask function is useful for constructing a modifier-mask and
state-mask masks. The keys found in the list keys are read and returned as
16-bit masks.

(DEFUN make-state-keys (state-mask)
  (DECLARE (TYPE mask16 mask)
       (VALUES return-list)
           (TYPE (LIST state-mask-key) return-list)))

state-mask
    Is a 16-bit mask of type mask16.

The make-state-key function takes the argument state-mask, and searches the
state-mask-key list for a match. If a match is found, the remaining portion of
the state-mask-key list is returned, otherwise NIL.


(DEFUN window-do-not-propagate-mask (window)
  (DECLARE (TYPE window window)
           (VALUES do-not-propagate-mask)
           (TYPE mask32 do-not-propagate-mask)))

Settable.

window  Specifies the window whose do-not-propagate-mask attribute is to be
        accessed.

Returns the value of the do-not-propagate-mask attribute for the specified
window.


(DEFUN window-event-mask (window)
  (DECLARE (TYPE window window)
           (VALUES event-mask?)
           (TYPE mask32 event-mask?)))

Settable.

window  Specifies the window whose event-mask attribute is to be accessed.

Returns the value of the event-mask attribute for the specified window.


4.4.8.  Override-Redirect

To control window placement or to add decoration, a window manager often
needs to intercept ("redirect") any map or configure request.  Pop-up
windows, however, need to be mapped without a window manager getting in the
way for quick response.  You can control if a window is to ignore these
structure control facilities by use of the override-redirect mask.

The default value for the override-redirect attribute is :off.  The
override-redirect attribute specifies whether map and configure requests on
this window should override a :substructure-redirect on the parent.
Typically window managers use this information to avoid tampering with
pop-up windows.


(DEFUN window-override-redirect (window)
  (DECLARE (TYPE window window)
           (VALUES override-redirect)
           (TYPE (MEMBER :on :off) override-redirect)))

Settable.

window  Specifies the window whose override-redirect attribute is to be
        accessed.

Returns the value of the override-redirect attribute for the specified
window.


4.4.9.  Colormap

The colormap attribute specifies which colormap, if any, best reflects the
true colors of the window.  The colormap must have the same visual type as
the window.  X servers capable of supporting multiple hardware colormaps may
use this information, and window managers may use it for install-colormap
requests (see section 6.4).  If you set the colormap attribute to :copy the
parent window's colormap is copied and used by its child.  The default value
for the colormap attribute is :copy.  Subsequent changes to the parent
window's colormap attribute do not affect the child window.  However, the
child window must have the same visual type as the parent.  The parent
window must not have a colormap attribute that is NIL.

The colormap is copied by sharing the colormap object between the child and
parent, not by making a complete copy of the colormap contents.


(DEFUN window-colormap (window)
  (DECLARE (TYPE window window)
           (VALUES colormap)
           (TYPE (OR NULL colormap) colormap)))

(DEFSETF window-colormap (window) (colormap)
  (DECLARE (TYPE window window)
           (TYPE (OR (MEMBER :copy) colormap) colormap)
           (VALUES colormap)
       (TYPE (OR NULL colormap) colormap)))

Settable.

window  Specifies the window whose colormap attribute is to be accessed.

Returns the value of the colormap attribute for the specified window.  A
value of :copy will never be returned, since the parent's colormap attribute
is actually copied, but the attribute may be set to :copy in a SETF form.
Changing the colormap of a window (defining a new map, not changing the
contents of the existing map) generates a :colormap-notify event.  Changing
the colormap of a visible window might have no immediate effect on the
screen (see install-colormap).


(DEFUN window-colormap-installed-p (window)
  (DECLARE (TYPE window window)
           (VALUES colormap-installed?)
           (TYPE boolean colormap-installed?)))

window  Specifies the window whose colormap state is to be returned.

This function returns non-null if the colormap associated with this window
is installed for the display.  Otherwise it returns NIL.


4.4.10.  Cursor

If a cursor is specified, it will be used whenever the pointer is in the
window.  If :none is specified, the parent's cursor will be used when the
pointer is in the window, and any change in the parent's cursor will cause
an immediate change in the displayed cursor.  The default value for the
cursor attribute is :none.  The cursor may be freed immediately if no
further explicit reference to it is made by calling free-cursor.

The X protocol does not allow retrieval of the cursor attribute value for a
window.  It is only settable.  In other words, it is a write only value.


(DEFSETF window-cursor (window) (cursor)
  (DECLARE (TYPE window window)
           (TYPE (OR (MEMBER :none) cursor) cursor)
           (VALUES cursor?)
           (TYPE cursor cursor?)))

window  Specifies the window whose cursor attribute is to be set.

border  Specifies the new value for cursor attribute.  It may be a cursor or
        :none as described above.

This SETF operation changes the cursor attribute of the window to the value
specified.  Changing the cursor of a root window to :none restores the
default cursor.


(DEFUN cursor-equal (cursor-1 cursor-2)
   (DECLARE (TYPE cursor cursor-1 cursor-2)))

cursor-1
cursor-2
    The cursor objects to be tested.

This function returns T if the two arguments are equivalent cursors and NIL if
they are not.


(DEFUN cursor-id (cursor)
   (DECLARE (TYPE cursor cursor)
        (VALUES id)
               (TYPE resource-id id)))

cursor    The cursor object to be accessed.

This function returns the unique resource-id that has been assigned to the
specified cursor by the server.


(DEFUN cursor-p (cursor)
   (DECLARE (TYPE cursor cursor)
        (VALUES boole)
        (TYPE boolean boole)))

cursor    The cursor object to be accessed.

This function returns a boolean; T if the argument is a cursor object and NIL
otherwise.


4.4.11.  Font

****more to be added here from font accessors...


A "font" is an array of glyphs (typically characters).  The protocol does no
translation or interpretation of character sets.  The client simply indicates
values used to index the glyph array.  A font contains additional metric
information to determine inter-glyph and inter-line spacing.



(DEFUN font-equal (font-1 font-2)
   (DECLARE (TYPE font font-1 font-2)))

font-1
font-2    The glyph arrays to be tested.

This function returns T if the two arguments are equivalent fonts and NIL if
they are not.


(DEFUN font-id (font)
   (DECLARE (TYPE font font)
        (VALUES id)
        (TYPE resource-id id)))

font     The glyph array which is to be accessed.

This function returns the unique resource-id that has been assigned to the
specified font by the server.


(DEFUN font-p (font)
   (DECLARE (TYPE font font)
        (VALUES boole)
        (TYPE boolean boole)))

font     The glyph array to be accessed.

This function returns a boolean; T if the argument is a font object and NIL
otherwise.

4.4.12.  Atoms

In CLX, an "atom" is a unique ID corresponding to a symbol or string name.
Atoms are used to identify properties, types, and selections.


(Defun find-atom (display name)
  (DECLARE (TYPE display display)
       (TYPE xatom name)
       (VALUES atom-name)
           (TYPE (OR NULL card29) atom-name)))


display    Specifies the connection to the X server.

name    Specifies the name (string or symbol) associated with the atom you
    want returned.

Returns the atom-id associated with a given string or symbol name if it
exists, otherwise NIL.  The only-if-exists option in Xlib is not an option in
CLX.  If you want the atom to be created if it does not exist, use atom-name.
The string should use the ISO Latin-1 encoding.  Case matters: the strings
"thing", "Thing", and "thinG" all designate different atoms.  Symbols are
always uppercase.  The lifetime of an atom is not tied to the interning
client.  Atoms remained defined until the server is reset.  Note that the atom
identifier would have been previously obtained the by calling intern-atom.


(DEFUN intern-atom (display name)
  (DECLARE (TYPE display display)
       (TYPE xatom name)
       (VALUES atom-id)
           (TYPE card29 atom-id)))

display    Specifies the connection to the X server.

name    Specifies the name (string or symbol) associated with the atom you
    want returned.

The intern-atom function returns the atom identifier associated with the given
string name.  You should use a null-terminated ISO Latin-1 string for name.
Case matters: the strings "thing", "Thing", and "thinG" all designate
different atoms.  Symbols are always uppercase.  The atom will remain defined
even after the client who defined it has gone away.  It will become undefined
only when the last connection to the X server closes.


(DEFUN atom-name (display atom-ID)
  (DECLARE (TYPE display display)
       (TYPE card29 atom-id)
       (VALUES atom-name)
           (TYPE keyword atom-name)))

display    Specifies the connection to the X server.

atom-id    Specifies the atom-id associated with the keyword name you want
    returned.

The atom-name function returns the keyword name associated with the atom
identifier you passed as the atom-id argument.  Atoms are accepted as strings
or symbols, however, they are always returned as keywords.  If the atom does
not exist, atom-name will create it.  The only-if-exists option in Xlib is not
an option in CLX.  If a test is warranted to see if the atom exists, but its
creation is not desirable, use find-name.


4.5.  Window Properties

Windows may have associated properties, consisting of a name, a type, a data
format, and some data.  The X Window System has a set of predefined
properties (for example, the name of a window, size hints, and so on), but
the protocol places no interpretation on properties, since they are intended
as a general purpose mechanism for clients to define arbitrary information
and associate it with windows.  For example, clients might share information
such as program names, documentation, and icon formats with a window manager
via properties.

For efficiency reasons atoms are used rather than a strings for the name and
type of a property.  The intern-atom function can be used to define or
obtain the atoms for new properties.  A property is stored in one of several
possible formats.  The X server can store the information as 8-bit
quantities, 16-bit quantities, or 32-bit quantities.  This permits the X
server to present the data in the byte order that the client expects.  The
type of a property is defined by other properties, which allows for
arbitrary extension in this type scheme.

                                      Note

     If you define further properties of complex types, you must write
     functions to encode and decode them yourself.  These functions must be
     carefully written if they are to be portable.  See Appendix ??  for
     further information about how to write such functions.

The predefined property names are:

        CUT_BUFFER0             RGB_GREEN_MAP
        CUT_BUFFER1             RGB_RED_MAP
        CUT_BUFFER2             RESOURCE_MANAGER
        CUT_BUFFER3             WM_CLASS
        CUT_BUFFER4             WM_CLIENT_MACHINE
        CUT_BUFFER5             WM_COMMAND
        CUT_BUFFER6             WM_HINTS
        CUT_BUFFER7             WM_ICON_NAME
        RGB_BEST_MAP            WM_ICON_SIZE
        RGB_BLUE_MAP            WM_NAME
        RGB_DEFAULT_MAP         WM_NORMAL_HINTS
        RGB_GRAY_MAP            WM_ZOOM_HINTS
                                WM_TRANSIENT_FOR

The predefined property types are:

        ARC                     POINT
        ATOM                    RGB_COLOR_MAP
        BITMAP                  RECTANGLE
        CARDINAL                STRING
        COLORMAP                VISUALID
        CURSOR                  WINDOW
        DRAWABLE                WM_HINTS
        FONT                    WM_SIZE_HINTS
        INTEGER
        PIXMAP


CLX provides functions with which you can obtain, change, update, or
interchange a window property.  In addition, CLX provides other utility
functions for predefined property operations.  See Chapter ??  for further
information about predefined property functions.


(DEFUN change-property (window property data type format
                        &key (mode :replace) (start 0) end transform)
  (DECLARE (TYPE window window)
           (TYPE xatom property type)
           (TYPE (MEMBER 8 16 32) format)
           (TYPE (SEQUENCE INTEGER) data)
           (TYPE (MEMBER :append :prepend :replace) :mode)
           (TYPE array-index :start)
           (TYPE (OR NULL array-index) :end)
           (TYPE (OR NULL (FUNCTION (T) INTEGER)) :transform)))

w       Specifies the window whose property you want to change.

property
        Specifies the atom for the name of the property which is to be
        changed.  The property remains defined even after the client who
        defined it closes its connection.

data    Specifies the new data for the property.

type    Specifies the atom for the type of the property.  The X server does
        not interpret the type but simply passes it back in later calls to
        the get-property function.

format  Specifies whether the data should be viewed as a sequence of 8-bit,
        16-bit, or 32-bit quantities.  This information allows the X server
        to correctly perform byte-swap operations as necessary.  Possible
        values are 8, 16, and 32.

:mode   Optionally specifies the mode of the operation.  The possible values
        are :append, :prepend, and :replace.  The default value is :replace.

:start
:end    Optionally specifies the sub-sequence which is extracted from data
        sequence.  The default 0 for start and NIL for end which means to
        use the whole sequence.

:transform
        Optionally specifies a function which is to be applied to each
        extracted element from the data sequence.  The default is NIL which
        indicates that no transformation is done.

The change-property function alters the property for the specified window
and causes the X server to generate a property-notify event on that window.
It does the following according to the value you assign to the mode
argument:

o    If the mode argument is :replace, change-property discards the previous
     property value.

o    If the mode argument is :append or :prepend, the type and format must
     match the existing property value.  If the property is undefined, it is
     treated as if it is defined with the correct type and format and zero
     length data.  For :append, the function appends the data onto the end
     of the existing data.  For :prepend, the function inserts the data
     before the beginning of the existing data.

The lifetime of a property is not tied to the storing client.  Properties
remain until explicitly deleted, until the window is destroyed, or until the
server resets.  See Section 2.4 for a discussion of what happens when the
connection to the X server is closed.  The maximum size of a property is
server dependent and, depending on the amount of memory the server has
available, can vary dynamically.


(DEFUN delete-property (window property)
  (DECLARE (TYPE window window)
           (TYPE xatom property)))

window  Specifies the window whose property you want to delete.

property
        Specifies the atom for the name of the property which is to be
        deleted.  The property remains defined even after the client who
        defined it closes its connection.

The delete-property function deletes the specified property if the property
is defined on the specified window.  It causes the X server to generate a
property-notify event on the window, unless the property does not exist.


(DEFUN get-property (window property
                     &key type (start 0) end delete-p (result-type 'LIST)
                          transform)
  (DECLARE (TYPE window window)
           (TYPE xatom property)
           (TYPE (OR NULL xatom) :type)
           (TYPE array-index :start)
           (TYPE (OR NULL array-index) :end)
           (TYPE boolean :delete-p)
           (TYPE T :result-type)
           (TYPE (OR NULL (FUNCTION (INTEGER) T)) :transform)
           (VALUES data return-type format bytes-after)
       (TYPE (SEQUENCE INTEGER) data)
       (TYPE (OR NULL xatom) return-type)
       (TYPE card8 format)
       (TYPE card32 bytes-after)))

window  Specifies the window whose property data, type atom, and format you
        want to obtain.

property
        Specifies the atom for the name of the property which is to be
        retrieved.  The property remains defined even after the client who
        defined it closes its connection.

:type   Optionally specifies the atom for the property type.  The default is
        NIL which allows matching any property type.  ??

:start  Optionally specifies the starting offset in the property data (in
        32-bit quantities) where data will be retrieved.  The default is
        zero which starts at the beginning of the data.

:end    Specifies the ending offset in the specified property (in 32-bit
        quantities) where data will stop being retrieved.  This is one
        beyond the last 32-bit quantity retrieved.  The default is 64000
        which will include all the data for most properties.

:delete-p
        An optional boolean value that determines whether the property is
        deleted from the window after the data is completely retrieved.
        Non-null specifies that the property is to be deleted and NIL
        indicates that it is retained.  The default is NIL.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequence should be created to
        return the data for this property.  The default is to return it in a
        list.

:transform
        Optionally specifies a function which is to be applied to each
        element of the property data that is retrieved and put into the
        sequence for the data return value.  The default is NIL which
        indicates that no transformation is done.

The get-property function returns the property data in a sequence, the atom
for the actual type of the property, the actual format of the property, and
the number of data bytes remaining to be read if a partial read was
performed as multiple values.  This function sets these return value
according to the following:

o    If the specified property does not exist for the specified window,
     get-property returns NIL for the data and type return values, and zero
     for the format and bytes-after return values.  In this case, the delete
     argument is ignored.

o    If the specified property exists, but its type does not match the
     specified type, get-property returns NIL for the data return value, the
     actual property type for the type return value, the actual property
     format (never zero) for the format return value, and the property
     length in bytes (even if the format return value is 16 or 32) for the
     bytes-after return value.  It also ignores the delete argument.

o    If the specified property exists, and either the type argument is NIL
     (??) or the specified type matches the actual property type,
     get-property returns the actual property type for the type return value
     and the actual property format (never zero) for the format return
     value.  It also returns a value for the bytes-after return value by
     defining the following values:

          N = actual length of the stored property in bytes
              (even if the format is 16 or 32)
          I = 4 * start
          T = N - I
          L = MINIMUM(T, 4 * (end - start))
          A = N - (I + L)

     The returned data starts at byte index I in the property (indexing from
     zero), and its length in bytes is L.  It is an error if end and start
     are specified such that L is negative.  The value of the bytes-after
     return value is A, which gives the number of trailing unread bytes in
     the stored property.

     If the delete argument is non-null and the bytes-after return value is
     zero the function deletes the property from the window and generates a
     property-notify event on the window.


(DEFUN rotate-properties (window properties &optional (delta 1))
  (DECLARE (TYPE window window)
           (TYPE (SEQUENCE xatom) properties)
           (TYPE int16 delta)))

window  Specifies the window whose property data, type atom, and format you
        want to obtain.

properties
        Specifies the sequence of atoms for the names of the properties
        which are to be rotated.  The properties remain defined even after
        the clients who defined them closes their connections.

delta   Specifies the rotation amount.

The rotate-properties function allows you to rotate the values for the
specified properties and causes the X server to generate a property-notify
event.  If the properties specified in the sequence are viewed as being
numbered starting from zero with N property name atoms in the sequence, then
the value associated with property I becomes the value associated with
property ((I + delta) MOD N), for all I from zero to (N - 1).  The effect is
to rotate the values of the properties by delta places around the virtual
ring of properties.  The rotation is to the left for positive values of
delta, and right for negative values of delta (this is the opposite of
actual X protocol request).  If (delta MOD N) is non-zero, the X server
generates a property-notify event for each property in the order that they
are listed in the sequence.  It is an error if a property name atom occurs
more than once in the sequence or no property with that name is defined for
the window and no properties are changed.


(DEFUN list-properties (window &key (result-type 'LIST))
  (DECLARE (TYPE window window)
           (TYPE T :result-type)
           (VALUES properties)
           (TYPE (SEQUENCE KEYWORD) properties)))

window  Specifies the window whose property list you want to obtain.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequence should be created to
        return the properties for the specified window.  The default is to
        return them in a list.

The list-properties function returns a sequence of keywords for the names of
the properties that are defined for the specified window.


4.6.  Window Selections

Selections are one method for applications to exchange data.  By using the
property mechanism, applications can exchange data of arbitrary types and
can negotiate the type of the data.  A selection can be thought of as an
indirect property with a dynamic type.  That is, rather than having the
property stored in the X server, the property is maintained by some client
(the owner).  A selection is global in nature, being thought of as belonging
to the user but maintained by clients, rather than being private to a
particular window subhierarchy or a particular set of clients.

Selections are communicated from an owner client to a requestor client.  The
owner has the data for the value of the selection, and the requestor
receives it.  A requestor wishing to obtain the value for a selection
provides:

o    The name of the selection.

o    The name of a property.

o    A window.

o    An atom representing the data type required.

If the selection is currently owned, the owner receives an event, and is
expected to:

o    Convert the contents of the selection to the requested data type.

o    Place this data in the named property on the named window.

o    Send the requestor an event to let it know the property is available.

Note that all data transferred between an owner and a requestor must
normally go via the server.  A client cannot assume that another client can
open the same files, ore even communicate directly.  The other client may be
be communicating with the server via a completely different networking
mechanism.  Thus, passing indirect references to data such as file names,
host names, and port numbers is permitted only if both clients specifically
agree.

CLX provides functions with which you can set, get, or request conversion of
window selections.  This allows applications to implement the notion of
current selection, which requires notification be sent to applications when
they no longer own the selection.  Applications that support selection often
highlight the current selection and need to be able to be informed when some
other application has acquired the selection in order to be able to
unhighlight the selection.

When a client asks for the contents of a selection, it specifies a selection
target type.  This target type can be used to control the transmitted
representation of the contents.  For example, if the selection is "the last
thing the user clicked on", and that is currently an image, then the target
type might specify whether the contents of the image should be sent in
XYFormat or ZFormat.

The target type can also be used to control the class of the contents that
are transmitted.  For example, a client could ask for the "looks" (fonts,
line spacing, indentation, and so forth) of a paragraph selection, instead
of the text of the paragraph.  The target type can also be used for other
purposes.  The semantics are not constrained by the protocol.


(DEFUN selection-owner (display selection)
  (DECLARE (TYPE display display)
           (TYPE xatom selection)
           (VALUES owner)
           (TYPE (OR NULL window) owner)))

Settable (see below).

display Specifies the display connection to the X server for the selection
        whose owner is being accessed.

selection
        Specifies the atom that names the selection whose owner you want
        returned.

The selection-owner function returns the window that currently owns the
specified selection.  If NIL is returned then there is no owner for the
selection.


(DEFUN set-selection-owner (display selection owner &optional time)
  (DECLARE (TYPE display display)
           (TYPE xatom selection)
           (TYPE timestamp time)
           (TYPE (OR NULL window) owner)
           (VALUES owner)
       (TYPE (OR NULL window) owner)))

(DEFSETF selection-owner (display selection &optional time) (owner)
  (DECLARE (TYPE display display)
           (TYPE xatom selection)
           (TYPE timestamp time)
           (TYPE (OR NULL window) owner)
           (VALUES owner)
       (TYPE (OR NULL window) owner)))

display Specifies the display connection to the X server for the selection
        whose owner is being set.

selection
        Specifies the atom that names the selection whose owner you want to
        set.

owner   Specifies the new owner of the specified selection.  You may specify
        a window or NIL for no owner.

time    Specifies the new last change time for the specified selection.  You
        can pass either a timestamp, expressed in milliseconds, or NIL which
        indicates the current time.

The set-selection-owner function (OR the equivalent SETF form) changes the
owner and last change time for the specified selection.  If the owner window
is specified as NIL, then the owner of the selection becomes NIL (that is,
no owner).  Otherwise, the owner of the selection becomes the window
specified.  A client must use a window which it created, since an event will
be used to reply.

The operation has no effect if the value you pass to the time argument is
earlier than the current last-change time of the specified selection or is
later than the current X server time.  Otherwise, the last-change time is
set to the specified time, with NIL being replaced by the current server
time.  This time value will normally be obtained from the timestamp of the
event triggering the acquisition of the selection.  Clients should not set
the time value to NIL (current server time), since if they do they have no
way of finding when they gained ownership of the selection.

If the new owner (whether a window or NIL) is not the same as the current
owner of the selection, and the current owner is not NIL, the current owner
is sent a selection-clear event.  If the client that is the owner of a
selection is later terminated (that is, its connection is closed) or if the
owner window it has specified in the request is later destroyed, the owner
of the selection automatically reverts to NIL, but the last-change time is
not affected.  The atom that names the selection is uninterpreted by the X
server.  The owner window of a selection can be retrieved by the
selection-owner function and is reported in selection-request and
selection-clear events.  Selections are global to the X server.


(DEFUN convert-selection (selection type requestor &optional property time)
  (DECLARE (TYPE xatom selection type)
           (TYPE window requestor)
           (TYPE (OR NULL xatom) property)
           (TYPE timestamp time)))

selection
        Specifies the atom that names the selection which you want to
        convert.

type    Specifies the atom for the target data type that the selection is to
        be converted to.

requestor
        Specifies the window which is requesting the conversion of the
        selection.  This is the window that the property, which contains the
        converted selection data, is placed on.

property
        Specifies the atom that names the property where the converted
        selection data is placed.  You also can pass NIL in which case the
        owner will choose a property.

time    Specifies the new last change time for the specified selection.  You
        can pass either a timestamp, expressed in milliseconds, or NIL which
        indicates the current time.

The convert-selection function requests that a selection be converted to the
specified target type and placed on the specified property:

o    If the specified selection has an owner, the X server sends a
     selection-request event to that owner.

o    If no owner for the specified selection exists, the X server generates
     a selection-notify event to the requestor with property NIL.  The
     arguments are passed on unchanged in either event.

There are two predefined selection atoms: "PRIMARY" and "SECONDARY".  See
Chapter ??  for more information on events, and in particular the
selection-notify event.


4.7.  Window Stacking Order

Sibling windows may "stack" on top of each other.  Windows above both
obscure and occlude lower windows.  This is similar to paper on a desk.
This relationship between sibling windows is known as the stacking order.

CLX provides functions with which you can raise or lower children of a
window.  If the windows are regarded as overlapping sheets of paper stacked
on a desk, then raising a window is analogous to moving the sheet to the top
of the stack while leaving its x and y location on the desk constant, and
lowering a window is analogous to moving the sheet to the bottom of the
stack while leaving its x and y location on the desk constant.  Raising a
mapped window may generate exposure events for the window and any mapped
subwindows that were formerly obscured and lowering a mapped window will
generate exposure events on any windows it formerly obscured.


(DEFUN circulate-window-down (window)
  (DECLARE (TYPE window window)))

window  The window whose child window is to be lowered.

The circulate-window-down function lowers the highest mapped child of the
specified window that partially or completely occludes another child to the
bottom of the stack.  Completely unobscured children are not affected.
Exposure processing is performed on formerly obscured windows.

If some other client has selected substructure-redirect on the window, then
a circulate-request event is generated, and no further processing is
performed.  Otherwise, the child window is lowered and a circulate-notify
event is generated if the window is actually restacked.


(DEFUN circulate-window-up (window)
  (DECLARE (TYPE window window)))

window  The window whose child window is to be raised.

The circulate-window-up function raises the lowest mapped child of the
specified window that is partially or completely occluded by another child
to the top of the stack.  Completely unobscured children are not affected.
Exposure processing is performed on formerly obscured windows.

If some other client has selected substructure-redirect on the window, then
a circulate-request event is generated, and no further processing is
performed.  Otherwise, the child window is raised and a circulate-notify
event is generated if the window is actually restacked.


4.8.  Window Hierarchy

All the windows in X are arranged in a strict hierarchy.  At the top of the
hierarchy are the root windows, which cover the display screens.  Each root
window is partially or completely covered by its child windows.  All
windows, except for root windows, have parents.  Child windows may in turn
have their own children.  In this way, a tree of arbitrary depth on each
screen can be created.  CLX provides several functions for examining and
modifying the window hierarchy.


(DEFUN drawable-root (drawable)
  (DECLARE (TYPE drawable drawable)
           (VALUES root-window?)
           (TYPE window root-window?)))

drawable
        The drawable whose root is to be returned.

This function returns the root window of the specified drawable.


(DEFUN query-tree (window &key (result-type 'LIST))
  (DECLARE (TYPE window window)
           (TYPE T :result-type)
           (VALUES children parent root)
           (TYPE (SEQUENCE window) children)
           (TYPE (OR NULL window) parent)
           (TYPE window root)))

window  The window whose tree is to be returned.  For this window, you
        obtain the sequence of its children, its parent, and its root as
        multiple values.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequence should be created to
        return the children of the specified window.  The default is to
        return them in a list.

The query-tree function returns the children windows, the parent window, and
the root window for the specified window.  The children are returned in
current stacking order, from bottom-most (FIRST) to top-most (LAST).


(DEFUN reparent-window (window parent x y)
  (DECLARE (TYPE window window parent)
           (TYPE int16 x y)))

window  Specifies the window which is to have its parent changed.

parent  Specifies the new parent for the specified window.

x
y       Specifies the x and y coordinates at which the specified window
        should be positioned in its new parent.  These coordinates are
        relative to the parent's origin, and specify the new position of the
        upper left outer corner of the window.

The reparent-window function changes a window's parent within a single
screen.  There is no way to move a window between screens.

The specified window is reparented by inserting it as a child of the
specified parent.  If the window is mapped an unmap-window operation is
automatically performed on the specified window.  The window is then removed
from its current position in the hierarchy and inserted as the child of the
specified parent.  The window is placed on top in the stacking order with
respect to sibling windows.

After reparenting the specified window a reparent-notify event is generated.
The override-redirect attribute of the window is passed on in this event.
Window manager clients normally should ignore this event if this attribute
is :on.  See Chapter ??  for more information on reparent-notify event
processing.  Finally, if the specified window was originally mapped, a
map-window operation is automatically performed on it.

The X server performs normal exposure processing on formerly obscured
windows.  It might not generate exposure events for regions from the initial
unmap-window operation if they are immediately obscured by the final
map-window operation.

It is an error if any of the following are true:

o    The new parent window is not on the same screen as the old parent
     window.

o    The new parent window is the specified window or an inferior of the
     specified window.

o    If the specified window has a :parent-relative background attribute and
     if the new parent window is not the same depth as the specified window.


4.9.  Translating Window Coordinates

Applications, mostly window managers, often need to perform a coordinate
transformation from the coordinate space of one window to another window or
need to determine which subwindow a coordinate lies in.  CLX provides a
function that fulfills these needs and avoids any race conditions by asking
the X server to perform this operation.


(DEFUN translate-coordinates (src src-x src-y dst)
  (DECLARE (TYPE window src dst)
           (TYPE int16 src-x src-y)
           (VALUES dst-x dst-y child)
           (TYPE (OR NULL int16) dst-x dst-y)
           (TYPE (OR NULL window) child)))

src     Specifies the source window which the coordinates are relative too.

src-x
src-y   Specify the x and y coordinates, within the source window, which are
        to be translated.

dst     Specifies the destination window whose coordinate space the
        coordinates are to translated to.

The translate-coordinates function takes the src-x and src-y coordinates
within the source window, relative to the source window's origin and returns
these coordinates relative to the destination window's origin as the first
values.  If the coordinates are contained in a mapped child of the
destination window, that child is returned as the third value.  If the
source and destination windows are not on the same screen, NIL is returned.


4.10.  Mapping Windows

A window is considered mapped if a map-window call has been made on it.
When windows are first created, they are not mapped because an application
may wish to create a window long before it is mapped to the screen.  A
mapped window may not be visible on the screen for one of the following
reasons:

o    It is obscured by another opaque sibling window.

o    One of its ancestors is not mapped.

o    It is entirely clipped by an ancestor.

Any output to a window not visible on the screen will be discarded.
Exposure events will be generated for the window when part or all of it
becomes visible on the screen.  A client will only receive the exposure
events if it has asked for them.  Windows retain their position in the
stacking order when unmapped.

A window manager may want to control the placement of subwindows.  If
substructure-redirect has been selected by a window manager on a parent
window (usually a root window), a map request initiated by other clients on
a child window is not performed, and the window manager would be sent a
map-request event.  However, if the override-redirect attribute on the child
had been set to :on (usually only on pop-up menus), the map request would be
performed.

A tiling window manager might decide to reposition and resize other client's
windows and then decide to map the window at its final location.  A window
manager that wants to provide decoration might reparent the child into a
frame first.  Only a single client at a time can select
substructure-redirect.

Similarly, a single client can select resize-redirect on a parent window.
Then, any attempt to resize the window is suppressed, and the client
(usually, a window manager) receives a resize-request event.  These
mechanisms allow arbitrary placement policy to be enforced by an external
window manager.


(DEFUN map-window (window)
  (DECLARE (TYPE window window)))

window  Specifies the window which is to be mapped.

The map-window function maps the window and all of its subwindows which have
had map requests.  A subwindow will appear on the screen as long as all of
its ancestors are mapped and not obscured by a sibling or are not clipped by
an ancestor.  Mapping a window that has an unmapped ancestor does not
display the window but marks it as eligible for display when the ancestor
becomes mapped.  Such a window is called unviewable.  When all its ancestors
are mapped, the window becomes viewable and will be visible on the screen if
it is not obscured by any sibling or ancestor.  This function has no effect
if the window is already mapped.

If the override-redirect attribute of the window is :off, and if some other
client has selected substructure-redirect on the parent window, then the X
server generates a map-request event, and the map-window function does not
map the window.  Otherwise, the window is mapped, and the X server generates
a map-notify event.

If the window becomes viewable and no earlier contents for it are
remembered, map-window tiles the window with its background.  If no
background was defined for the window, the existing screen contents are not
altered, and the X server generates one or more expose events.  If a
backing-store was maintained while the window was unmapped, no expose events
are generated.  If a backing-store will now be maintained, a full window
exposure is always generated.  Otherwise, only visible regions may be
reported.  Similar tiling and exposure take place for any newly viewable
inferiors.

If the window is an input-output window, map-window generates expose events
on each input-output window that it causes to become displayed.  If the
client maps and paints the window, and if the client begins processing
events, the window will be painted twice.  To avoid this, the client should
request exposure events, map the window, and process input events normally.
The event list will include expose for each window that has appeared on the
screen.  The client's normal response to an expose event should be to
repaint the window.  This method usually leads to simpler programs and to
proper interaction with window managers.


(DEFUN map-subwindows (window)
  (DECLARE (TYPE window window)))

window  Specifies the window whose subwindows are to be mapped.

The map-subwindows function maps all subwindows for a specified window in
top-to-bottom stacking order.  The X server generates an expose event on
each newly displayed window.  This is much more efficient than mapping many
windows one at a time, because the server needs only perform much of the
work once for all of the windows rather than for each window.


(DEFUN window-map-state (window)
  (DECLARE (TYPE window window)
           (VALUES map-state)
           (TYPE (MEMBER :unmapped :unviewable :viewable) map-state)))

window  Specifies the window whose map state is to be returned.

This function returns the map state of the specified window.  A window is
:unviewable if it is mapped but some ancestor is unmapped.


4.11.  Unmapping Windows

CLX provides functions with which you can unmap a window or all subwindows.
Windows retain their position in the stacking order when unmapped.


(DEFUN unmap-window (window)
  (DECLARE (TYPE window window)))

window  Specifies the window which is to be unmapped.

The unmap-window function unmaps the specified window and causes the X
server to generate an unmap-notify event.  If the specified window is
already unmapped, unmap-window has no effect.  Normal exposure processing on
formerly obscured windows is performed.  Any child window will no longer be
visible until another map call is made on the parent.  In other words, the
subwindows are still mapped but not visible until the parent is mapped.
Unmapping a window will generate exposure events on windows that were
formerly obscured by it and its children.


(DEFUN unmap-subwindows (window)
  (DECLARE (TYPE window window)))

window  Specifies the window whose subwindows are to be unmapped.

The unmap-subwindows function unmaps all subwindows for the specified window
in bottom to top stacking order.  It causes the X server to generate an
unmap-notify event on each subwindow and exposure events on formerly
obscured windows.  Using this function is much more efficient than unmapping
multiple windows one at a time, because the server needs only perform much
of the work once for all of the windows rather than for each window.


4.12.  Destroying Windows

CLX provides functions with which you can destroy a window or destroy all
subwindows of a window.


(DEFUN destroy-window (window)
  (DECLARE (TYPE window window)))

window  Specifies the window which is to be destroyed.

The destroy-window function destroys the specified window as well as all of
its subwindows and causes the X server to generate a destroy-notify event
for each window.  The window should never again be referenced.  If the
specified window is mapped, it is unmapped automatically.  The window and
all of its inferiors are then destroyed, and a destroy-notify event is
generated for each window.  The ordering of the destroy-notify events is
such that for any given window being destroyed, destroy-notify is generated
on any inferiors of the window before being generated on the window itself.
The ordering among siblings and across sub-hierarchies is not otherwise
constrained.  If the window you specified is a root window, no windows are
destroyed.  Destroying a mapped window will generate exposure events on
other windows that were obscured by the window being destroyed.


(DEFUN destroy-subwindows (window)
  (DECLARE (TYPE window window)))

window  Specifies the window whose subwindows are to be destroyed.

The destroy-subwindows function destroys all inferior windows of the
specified window, in bottom to top stacking order.  It causes the X server
to generate a destroy-notify event for each window.  If any mapped
subwindows were actually destroyed, destroy-subwindows causes the X sever to
generate exposure events on the specified window.  This is much more
efficient than deleting many windows one at a time because much of the work
need only be performed once for all of the windows rather than for each
window.  The subwindows should never again be referenced.  Note that by
default, windows are destroyed when a connection is closed.  See section 2.4
for more information.



                  Chapter 5

                              Graphic Contexts


Most information about performing graphics (for example, foreground color,
background color, line style, and so on) are stored in resources called
graphic contexts.  Most graphic operations (see chapter 7) take a graphic
context (also referred to as a GContext, or GC) as an argument and use the
values in it to control the actual graphic operation.  In addition,
extensions to X may add additional components to graphic contexts.

CLX implements a write back cache for all elements of a graphic context that
are not resource identifiers to allow it to implement the transparent
coalescing of changes.  For example, a SETF of the foreground element in a
graphic context followed by a SETF of the line-style element will result in
only a single ChangeGC protocol request to the server.  Since graphic contexts
are neither expected nor encouraged to be shared between client applications
this caching should present no problems.  Applications cannot share graphic
contexts without external synchronization.  Therefore, sharing graphic
contexts between applications is highly discouraged.

For optimum performance, you should draw as much as possible with the same
graphic context (without changing its components).  The costs of changing
components relative to using different graphic contexts depends upon the
display hardware and the server implementation.  In addition, it is quite
likely that some amount of graphic context information will be cached in the
server and that a server can only cache a small number of graphic contexts.

This chapter explains of the CLX functions you can use to:

o    Create graphic contexts

o    Obtain information about a graphic context

o    Change elements of a graphic context

o    Copy a graphic context

o    Free a graphic context


5.1.  Creating Graphic Contexts


(DEFUN create-gcontext (&key arc-mode background (cache-p t) cap-style
                             clip-mask clip-ordering clip-x clip-y
                             dash-offset dashes drawable exposures
                             fill-rule fill-style font foreground function
                             join-style line-style line-width plane-mask
                             stipple subwindow-mode tile ts-x ts-y)
  (DECLARE (TYPE (OR NULL (MEMBER :chord :pie-slice)) :arc-mode)
           (TYPE (OR NULL pixel) :background :foreground :plane-mask)
           (TYPE boolean :cache)
           (TYPE (OR NULL (MEMBER :unsorted :y-sorted :yx-banded
                                  :yx-sorted))
                 :clip-ordering)
           (TYPE (OR NULL (MEMBER :butt :not-last :projecting :round))
                 :cap-style)
           (TYPE (OR NULL (MEMBER :none) pixmap rect-seq) :clip-mask)
           (TYPE (OR NULL int16) :clip-x :clip-y :ts-x :ts-y)
           (TYPE (OR NULL card16) :dash-offset :line-width)
           (TYPE (OR NULL (OR card8 (SEQUENCE card8))) :dashes)
           (TYPE drawable drawable)
           (TYPE (OR NULL (MEMBER :off :on)) :exposures)
           (TYPE (OR NULL (MEMBER :even-odd :winding)) :fill-rule)
           (TYPE (OR NULL (MEMBER :opaque-stippled :solid :stippled :tiled))
                 :fill-style)
           (TYPE (OR NULL fontable) :font)
           (TYPE (OR NULL boole-constant) :function)
           (TYPE (OR NULL (MEMBER :bevel :miter :round)) :join-style)
           (TYPE (OR NULL (MEMBER :dash :double-dash :solid)) :line-style)
           (TYPE (OR NULL pixmap) :stipple :tile)
           (TYPE (OR NULL (MEMBER :clip-by-children :include-inferiors))
                 :subwindow-mode)
           (VALUES gcontext?)
           (TYPE gcontext gcontext?)))

:cache  Specifies if this graphic context should be cached locally by CLX.
        If NIL then the state is not cached, otherwise a local cache will be
        kept.  The default is to keep a local cache.

:drawable
        Specifies the drawable whose root and depth are to be associated
        with this graphic context.  This is a required keyword argument.

:arc-mode
:background
:cap-style
:clip-mask
:clip-ordering
:clip-x
:clip-y
:dash-offset
:dashes
:exposures
:fill-rule
:fill-style
:font
:foreground
:function
:join-style
:line-style
:line-width
:plane-mask
:stipple
:subwindow-mode
:tile
:ts-x
:ts-y   Specifies the values for the elements of the graphic context which
        are to be set at creation time.  Only the non-null attributes are
        passed on in the request, but for effective caching assumptions are
        made about what the actual protocol defaults are.  See Section 5.3
        for further information on the graphic context elements.

The create-gcontext function creates, initializes, and returns a graphic
context.  The graphic context can be used with any destination drawable
having the same root and depth as the specified drawable.  It is an error to
use it with other drawables.

All of the graphic context components are set to the values that are
specified by the keyword arguments, except that a value of NIL causes the
default value to be used.  These default values are as follows:

  -------------------------------------------------------------------------
  Component             Default Value
  -------------------------------------------------------------------------
  arc-mode              :pie-slice
  background            1
  cap-style             :butt
  clip-mask             :none
  clip-ordering         :unsorted
  clip-x                0
  clip-y                0
  dash-offset           0
  dashes                4 (that is, the list [4, 4])
  exposures             :on
  fill-rule             :even-odd
  fill-style            :solid
  font                  <implementation dependent>
  foreground            0
  function              BOOLE-1
  join-style            :miter
  line-style            :solid
  line-width            0
  plane-mask            All ones
  stipple               Pixmap of unspecified size filled with ones
  subwindow-mode        :clip-by-children
  tile                  Pixmap of an unspecified size filled with the
                        foreground pixel (that is, the client specified
                        pixel if any, else 0)
  ts-x                  0
  ts-y                  0
  -------------------------------------------------------------------------

Note that foreground and background do not default to any values that are
likely to be useful on a color display.  Since specifying a NIL value means
use the default, this implies for clip-mask that an empty rectangle sequence
cannot be specified as an empty list, :none must be used instead.
Specifying a stringable for font will cause an implicit open-font call to
occur.

If cache-p is non-null, then the graphic context state is cached locally,
and changing a component will have no effect unless the new value differs
from the cached value.  Changes to a graphic context (SETF and
with-gcontext) are always deferred regardless of the cache mode, and sent to
the server only when required by a local operation or by an explicit call to
force-gcontext-changes.


5.2.  Graphic Context Functions

CLX provides a number of useful functions that return data from a graphic
context.  All other elements (that is, those for which no functions are
defined) are internal to CLX and must not be used.  The following lists the
functions and what data they return for the specified graphic context.


(DEFUN gcontext-equal (gcontext-1 gcontext-2)
  (DECLARE (TYPE gcontext gcontext-1 gcontext-2)
           (VALUES equal?)
           (TYPE boolean equal?)))

gcontext-1
gcontext-2
        The graphic contexts that are to be compared for equality.

This function returns non-null if the two graphic contexts arguments have
equivalent attribute values and NIL if they do not.


(DEFUN gcontext-id (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES id)
           (TYPE resource-id id)))

gcontext
        The graphic context whose resource id is to be accessed.

This function returns the unique id that has been assigned to the specified
graphic context by the server.


(DEFUN gcontext-p (gcontext)
  (DECLARE (TYPE T gcontext)
           (VALUES gcontext?)
           (TYPE boolean gcontext?)))

gcontext
        The data object which is to be tested to see if it is a graphic
        context.

This function returns non-null if the argument is a graphic context and NIL
otherwise.


5.3.  Graphic Context Attributes

The attributes of a graphic context are the values that are used by the
graphic operations to control their execution.  This sections describes what
each of these attributes are used for and the CLX functions that can be used
to access and change them.

The value returned by these accessing functions will be NIL if the last
value stored is unknown (e.g., the cache was turned off, or the component
was copied from a graphic context whose state was unknown).


5.3.1.  Arc-Mode

The arc-mode attribute of a graphic context controls what kind of filling
(IF any) is done by the draw-arcs function.  A value of :chord specifies
that arcs will be filled inward to the chord between the end points of the
arc.  While :pie-slice specifies that arcs will be inward to the center
point of the arc creating a pie slice effect.


(DEFUN gcontext-arc-mode (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES arc-mode)
           (TYPE (MEMBER :chord :pie-slice) arc-mode)))

Settable.

gcontext
        The graphic context whose arc-mode attribute is to be accessed.

This function returns the arc-mode attribute of the specified graphic
context.


5.3.2.  Background and Foreground

The foreground attribute of a graphic context specifies the pixel value that
is drawn for set bits in a bitmap and for bits set by a graphic operation.
The background attribute specifies the pixel value that is drawn for bits
that are not set in a bitmap and for bits that are cleared by a graphics
operation, such as the gaps in dashed lines.


(DEFUN gcontext-background (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES background)
           (TYPE card32 background)))

Settable.

gcontext
        The graphic context whose background attribute is to be accessed.

This function returns the background attribute of the specified graphic
context.


(DEFUN gcontext-foreground (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES foreground)
           (TYPE card32 foreground)))

Settable.

gcontext
        The graphic context whose foreground attribute is to be accessed.

This function returns the foreground attribute of the specified graphic
context.


5.3.3.  Cap-Style and Join-Style

The cap-style attribute of a graphic context defines how the end points of a
path are drawn.  The possible values and how they are interpreted are:

:butt           Square at the end point (perpendicular to the slope of the
                line) with no projection beyond.

:not-last       Equivalent to :butt, except that for a line-width of zero
                or one the final end point is not drawn.

:projecting     Square at the end, but the path continues beyond the
                end point for a distance equal to half the line-width.  This
                is equivalent to :butt for line-width zero or one.

:round          A circular arc with the diameter equal to the line-width,
                centered on the end point.  This is equivalent to :butt for
                line-width zero or one.

For a line with coincident end points when the cap-style is applied to both
end points, the semantics depends on the line-width and the cap-style as
follows:

:butt           thin    Device dependent, but the desired effect is that a
                        single pixel is drawn.

:butt           wide    Nothing is drawn.

:not-last       thin    Device dependent, but the desired effect is that
                        nothing is drawn.

:projecting     thin    Same as :butt/thin.

:projecting     wide    The closed path is a square, aligned with the
                        coordinate axes, centered at the end point, with
                        sides equal to the line-width

:round          wide    The closed path is a circle, centered at the end
                        point, with diameter equal to the line-width.

:round          thin    Same as :butt/thin.

The join-style attribute of a graphic context defines how the corners are
drawn for connected wide lines.  The possible values and how they are
interpreted are:

:bevel          Uses :butt end point styles with the triangular notch filled.

:miter          The outer edges of two lines extend to meet at an angle.

:round          A circular arc with diameter equal to the line-width,
                centered on the join point.

For a line with coincident end points when the join-style is applied at one
or both end points, the effect is as if the line was removed from the
overall path.  However, if the total path consists of or is reduced to a
single point joined with itself, the effect is the same as when the
cap-style is applied at both end points.


(DEFUN gcontext-cap-style (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES cap-style)
           (TYPE (MEMBER :butt :not-last :projecting :round) cap-style)))

Settable.

gcontext
        The graphic context whose cap-style attribute is to be accessed.

This function returns the cap-style attribute of the specified graphic
context.


(DEFUN gcontext-join-style (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES join-style)
           (TYPE (MEMBER :bevel :miter :round) join-style)))

Settable.

gcontext
        The graphic context whose join-style attribute is to be accessed.

This function returns the join-style attribute of the specified graphic
context.


5.3.4.  Clip-Mask, Clip-Ordering, Clip-X, Clip-Y, and Subwindow-Mode

The clip-mask attribute of a graphic context affects all graphic operations
and is used to restrict writes to the destination drawable.  The clip-mask
does not clip the sources of graphic operations.  A value of :none for
clip-mask indicates that no clipping is to be done and the pixels are always
drawn.

If a pixmap is specified as the clip-mask, it must have depth one and have
the same root as the graphic context that it is being specified as the
clip-mask for.  Pixels where the clip-mask has a one bit are drawn.  Pixels
outside the area covered by the clip-mask or where the clip-mask has a zero
bit are not drawn.

If a sequence of rectangles is specified as the clip-mask the output is
clipped to remain contained within the rectangles.  The rectangles should be
non-intersecting, or the results of the graphic operations will be
undefined.  The rectangle coordinates are interpreted relative to the clip
origin.  Note that the sequence of rectangles can be empty, which
effectively disables output.  This is the opposite of setting the clip-mask
to :none.

If known by the client the ordering of the rectangles specified for the
clip-mask attribute can be specified with the clip-ordering attribute.  This
may provide faster operation by the server.  A value of :unsorted means the
rectangles are in arbitrary order.  A value of :y-sorted means that the
rectangles are non-decreasing in their Y origin.  A :yx-sorted value is like
:y-sorted with the additional constraint that all rectangles with an equal Y
origin are non-decreasing in their X origin.  A :yx-banded value
additionally constrains :yx-sorted by requiring that, for every possible Y
scan line, all rectangles that include that scan line have an identical Y
origins and Y extents.  If an incorrect ordering is specified, the X server
may generate an error, but it is not required to do so.  If no error is
generated, the results of the graphic operations are undefined.

The clip-x and clip-y attributes specify the origin for the clip-mask
whether it is a pixmap or a sequence of rectangles.  These coordinates are
interpreted relative to the origin of whatever destination drawable is
specified in a graphic operation.

The subwindow-mode attribute of a graphic context specifies whether
subwindows obscure the contents of their parent window during a graphic
operation.  For a value of :clip-by-children, both source and destination
windows are clipped by all viewable input-output class children.  This
clipping is in addition to the clipping provided by the clip-mode attribute.
For a value of :include-inferiors, neither the source nor destination window
is clipped by its inferiors.  This will result in including subwindow
contents in the source and drawing through subwindow boundaries of the
destination.  The use of :include-inferiors on a window of one depth with
mapped inferiors of differing depth is not illegal, but the semantics are
not defined by the core protocol.


(DEFUN gcontext-clip-mask (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES clip-mask ordering)
           (TYPE (OR NULL (MEMBER :none) pixmap rect-seq) clip-mask)
           (TYPE (OR NULL (MEMBER :unsorted :y-sorted :yx-banded :yx-sorted))
                 ordering)))

Settable (see below).

gcontext
        The graphic context whose clip-mask and clip-ordering attributes are
        to be accessed.

This function returns the clip-mask attribute of the specified graphic
context and the associated clip-ordering (if the clip mask is a sequence of
rectangles) as multiple values.


(DEFUN set-gcontext-clip-mask (gcontext ordering clip-mask)
  (DECLARE (TYPE gcontext gcontext)
           (TYPE (OR NULL
                     (MEMBER :unsorted :y-sorted :yx-sorted :yx-banded))
                 ordering)
           (TYPE (OR (MEMBER :none) pixmap rect-seq) clip-mask)
           (VALUES clip-mask)
           (TYPE '(or (member :none) pixmap rect-seq) clip-mask)))

(DEFSETF gcontext-clip-mask (gcontext &optional ordering) (clip-mask)
  (DECLARE (TYPE gcontext gcontext)
           (TYPE (OR NULL
                     (MEMBER :unsorted :y-sorted :yx-banded :yx-sorted))
                 ordering)
           (TYPE (OR (MEMBER :none) pixmap rect-seq) clip-mask)
           (VALUES clip-mask)
       (TYPE '(or (member :none) pixmap rect-seq) clip-mask)))

gcontext
        Specifies the graphic context whose clip-mask and clip-ordering
        attributes are being set.

ordering
        If the new clip-mask is a sequence of rectangles then this specifies
        how the rectangles are ordered within the sequence.

clip-mask
        Specifies the new value of the clip-mask attribute for the specified
        graphic context.

A nil clip-mask is transformed to an empty vector


(DEFUN gcontext-clip-x (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES clip-x)
           (TYPE int16 clip-x)))

Settable.

gcontext
        The graphic context whose clip-x attribute is to be accessed.

This function returns the clip-x attribute of the specified graphic context.


(DEFUN gcontext-clip-y (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES clip-y)
           (TYPE int16 clip-y)))

Settable.

gcontext
        The graphic context whose clip-y attribute is to be accessed.

This function returns the clip-y attribute of the specified graphic context.


(DEFUN gcontext-subwindow-mode (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES subwindow-mode)
           (TYPE (MEMBER :clip-by-children :include-inferiors)
             subwindow-mode)))

Settable.

gcontext
        The graphic context whose subwindow-mode attribute is to be accessed.

This function returns the subwindow-mode attribute of the specified graphic
context.


5.3.5.  Dash-Offset, Dashes, and Line-Style

The dash-offset attribute of a graphic context defines the phase of the
pattern contained in the dashes attribute.  This phase specifies how many
elements (pixels) into the path the pattern should actually begin in any
single graphics operation.  Dashing is continuous through path elements
combined with a join-style, but is reset to the dash-offset each time a
cap-style is applied at a line end point.

The dashes attribute in a graphic context specifies the pattern that is used
for graphic operations which use the dashed line styles.  It is a non-null
sequence with each element representing the length of a single dash or
space.  The initial and alternating elements (2nd, 4th, and so on) of the
dashes are the even dashes, while the others are the odd dashes.  An odd
length sequence is equivalent to the same sequence concatenated with itself
to produce an even length sequence.  All of the elements of a dashes
sequence must be non-zero.

Specifying a single integer value, N, for the dashes attribute is an
abbreviated way of specifying a two element sequence with both elements
equal to the specified value [N, N].

The unit of measure for dashes is the same as in the ordinary coordinate
system.  Ideally, a dash length is measured along the slope of the line, but
server implementations are only required to match this ideal for horizontal
and vertical lines.

The line-style attribute of a graphic context specifies how (which sections
of) lines are drawn for a path in graphic operations.  The possible values
and their meanings are:

:solid          The full path is drawn.

:double-dash    The full path is drawn, but the even dashes are filled
                differently than the odd dashes with :butt style used where
                even and odd dashes meet (see fill-style, section 5.3.7).

:on-off-dash    Only the even dashes are drawn, with cap-style applied to
                all internal ends of the individual dashes, except :not-last
                is treated as :butt.


(DEFUN gcontext-dash-offset (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES dash-offset)
           (TYPE card16 dash-offset)))

Settable.

gcontext
        The graphic context whose dash-offset attribute is to be accessed.

This function returns the dash-offset attribute of the specified graphic
context.


(DEFUN gcontext-dashes (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES dashes)
           (TYPE (OR card8 (SEQUENCE card8)) dashes)))

Settable.

gcontext
        The graphic context whose dashes attribute is to be accessed.

This function returns the dashes attribute of the specified graphic context.
The sequence must be non-empty and the elements must be non-zero.


(DEFUN gcontext-line-style (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES line-style)
           (TYPE (MEMBER :dash :double-dash :solid) line-style)))

Settable.

gcontext
        The graphic context whose line-style attribute is to be accessed.

This function returns the line-style attribute of the specified graphic
context.


5.3.6.  Exposures

The exposures attribute in a graphic context controls graphics-expose event
generation for calls to the copy-area and copy-plane functions (AND any
similar functions defined by any extensions).  A value of :on specifies you
want graphics-expose events to be reported when calling the copy-area and
copy-plane functions with this graphic context and a value of :off indicates
that you do not want them reported.


(DEFUN gcontext-exposures (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES exposures)
           (TYPE (MEMBER :off :on) exposures)))

Settable.

gcontext
        The graphic context whose exposures attribute is to be accessed.

This function returns the exposures attribute of the specified graphic
context.


5.3.7.  Fill-Rule and Fill-Style

The fill-rule attribute in a graphic context specifies the rule to use in
deciding what pixels are inside (drawn) of paths given for filled polygons.
It may be specified as either :even-odd or :winding.

The :even-odd rule defines a point as inside if any infinite ray starting at
the point crosses the path an odd number of times.  Tangencies do not count
as a crossing.

For :winding, a point is considered inside if any infinite ray starting at
the point crosses an unequal number of clockwise and counterclockwise
directed path segments.  A clockwise directed path segment is one which
crosses the ray from left to right as observed from the point.  A
counterclockwise segment is one which crosses the ray from right to left as
observed from the point.  The case where a directed line segment is
coincident with the ray is uninteresting because you can simply choose a
different ray that is not coincident with a segment.

For both :even-odd and :winding, a point is infinitely small, and the path
is an infinitely thin line.  A pixel is inside if the center point of the
pixel is inside, and the center point is not on the boundary.  If the center
point is on the boundary, the pixel is inside if and only if the polygon
interior is immediately to its right (x increasing direction).  Pixels with
centers along a horizontal edge are a special case and are inside if and
only if the polygon interior is immediately below (y increasing direction).

The fill-style attribute of a graphic context defines the contents of the
source for line, text, and fill graphic operations.  It determines whether
the source image is drawn with a solid color, a tile, or a stippled tile.
The possible values and their meanings are:

:opaque-stippled        Filled with a tile with the same width and height as
                        stipple, but with the background value used
                        everywhere stipple has a zero and the foreground
                        pixel value used everywhere stipple has a one.

:solid                  Filled with the foreground pixel value.

:stippled               Filled with the foreground pixel value masked by
                        stipple.

:tiled                  Filled with tile.

When drawing lines with line-style :double-dash, the filling of the odd
dashes are controlled by the fill-style in the following manner:

:opaque-stippled        Same as for even dashes.

:solid                  Filled with the background pixel value.

:stippled               Filled with the background pixel value masked by
                        stipple.

:tiled                  Filled the same as the even dashes.


(DEFUN gcontext-fill-rule (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES fill-rule)
           (TYPE (MEMBER :even-odd :winding) fill-rule)))

Settable.

gcontext
        The graphic context whose fill-rule attribute is to be accessed.

This function returns the fill-rule attribute of the specified graphic
context.


(DEFUN gcontext-fill-style (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES fill-style)
           (TYPE (MEMBER :opaque-stippled :solid :stippled :tiled)
                 fill-style)))

Settable.

gcontext
        The graphic context whose fill-style attribute is to be accessed.

This function returns the fill-style attribute of the specified graphic
context.


5.3.8.  Font

The font attribute in a graphic context defines the default text font that
is used in text drawing operations.


(DEFUN gcontext-font (gcontext &optional metrics-p)
  (DECLARE (TYPE gcontext gcontext)
           (TYPE boolean metrics-p)
           (VALUES font)
           (TYPE (OR NULL font) font)))

(DEFSETF gcontext-font (gcontext) (font)
  (DECLARE (TYPE gcontext gcontext)
           (TYPE fontable font)
           (VALUES font)
       (TYPE (OR NULL font) font)))

Settable.

gcontext
        The graphic context whose font attribute is to be accessed.

metrics-p
        Specifies whether or not a pseudo font is returned when the real
        font stored in the graphic context is not known.  The default is NIL
        which means don't return a pseudo font.

This function returns the font attribute of the specified graphic context.
If the stored font is known, it is returned.  If it is not known and the
metrics-p argument is NIL, then NIL is returned.  If the font is not known
and metrics-p is true, then a pseudo font is constructed and returned.  For
a constructed pseudo font, full metric and property information can be
obtained, but it does not have a name or a resource-id, and attempts to use
it where a resource-id is required will result in an invalid-font error.

When setting the value of the font attribute either a font object or a font
name can be used.  If a font name is passed an automatic call to open-font
is made get the font object.


5.3.9.  Function and Plane-Mask

You use the graphic context function attribute when you update a section of
the screen (destination) with bits from somewhere else (source).  The
function defines how the new destination bits are to be computed from the
source bits and the old destination bits.  There are 16 such functions
defined in CLX which match the boolean operation-code constants defined in
the Common LISP language.  The functions and their corresponding constants
are:

  ------------------------------------------------------------------------
  Constant      Example                         Operation
  Name          (src=0011, dst=0101)            Performed
  ------------------------------------------------------------------------
  BOOLE-CLR     0000    0                       set to zero
  BOOLE-SET     1111    1                       set to one
  BOOLE-1       0011    src                     copy source
  BOOLE-2       0101    dst                     no-operation
  BOOLE-C1      1100    (NOT src)               complement source
  BOOLE-C2      1010    (NOT dst)               complement destination
  BOOLE-AND     0001    (src AND dst)           and
  BOOLE-IOR     0111    (src OR dst)            inclusive or
  BOOLE-XOR     0110    (src XOR dst)           exclusive or
  BOOLE-EQV     1001    ((NOT src) XOR dst)     equivalence (exclusive nor)
  BOOLE-NAND    1110    (NOT (src AND dst))     not-and
  BOOLE-NOR     1000    (NOT (src OR dst))      not-or
  BOOLE-ANDC1   0100    ((NOT src) AND dst)     and complement of source
                                                with destination
  BOOLE-ANDC2   0010    (src AND (NOT dst))     and source with complement
                                                of destination
  BOOLE-ORC1    1101    ((NOT src) OR dst)      or complement of source
                                                with destination
  BOOLE-ORC2    1011    (src OR (NOT dst))      or source with complement
                                                of destination
  ------------------------------------------------------------------------

The plane-mask attribute in a graphic context specifies which planes of the
display are to be modified during graphic operations.  There is one bit in
the mask per memory plane in the display.  A monochrome display has only one
plane which will be assigned the least significant bit of the plane-mask.
As planes are added to the display hardware, they will occupy more
significant bits in the plane mask.

In graphic operations, given a source and destination pixel, the result is
computed bitwise on corresponding bits of the pixels.  That is, a boolean
operation is performed in each bit plane.  The plane-mask restricts the
operation to a subset of the planes.  That is, the result is computed
according to the following formula:

        ((src FUNCTION dst) AND plane-mask) OR (dst AND (NOT plane-mask))


(DEFUN gcontext-function (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES function)
           (TYPE boole-constant function)))

Settable.

gcontext
        The graphic context whose function attribute is to be accessed.


(DEFUN gcontext-plane-mask (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES plane-mask)
           (TYPE card32 plane-mask)))

Settable.

gcontext
        The graphic context whose plane-mask attribute is to be accessed.


5.3.10.  Line-Width

The line-width is measured in pixels and can be greater than or equal to one
(wide line) or can be the special value zero (thin line).

Wide lines are drawn centered on the path described by the graphic
operation.  Unless otherwise specified by the join or cap style, the
bounding box of a wide line with end points [x1, y1], [x2, y2], and width w
is a rectangle with vertices at the following real coordinates:

        [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
        [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]

Where sn is the sine of the angle of the line and cs is the cosine of the
angle of the line.  A pixel is part of the line and, hence, is drawn, if the
center of the pixel is fully inside the bounding box (which is viewed as
having infinitely thin edges).  If the center of the pixel is exactly on the
bounding box, it is part of the line if and only if the interior is
immediately to its right (x increasing direction).  Pixels with centers on a
horizontal edge are a special case and are part of the line if and only if
the interior is immediately below (y increasing direction).

Thin lines (zero line-width) are always one pixel wide lines drawn using an
unspecified, device dependent algorithm.  There are only two constraints on
this algorithm.

1.   If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another
     line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point
     [x,y] is touched by drawing the first line if and only if the point
     [x+dx,y+dy] is touched by drawing the second line.

2.   The effective set of points comprising a line cannot be affected by
     clipping.  That is, a point is touched in a clipped line if and only if
     the point lies inside the clipping region and the point would be
     touched by the line when drawn unclipped.

A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels as a
wide line drawn from [x2,y2] to [x1,y1], not counting cap and join styles.
Implementors are encouraged to make this property true for thin lines, but
it is not required.  A line-width of zero may differ from a line-width of
one in which pixels are drawn.  This permits the use of many manufacturer's
line drawing hardware, which may run much faster than the more precisely
specified wide lines.

In general, drawing a thin line will be faster than drawing a wide line of
width one.  However, because of their different drawing algorithms, thin
lines may not mix well, aesthetically speaking, with wide lines.  If it is
desirable to obtain precise and uniform results across all displays, a
client should always use a line-width of one, rather than a line-width of
zero.


(DEFUN gcontext-line-width (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES line-width)
           (TYPE card16 line-width)))

Settable.

gcontext
        The graphic context whose line-width attribute is to be accessed.


5.3.11.  Stipple, Tile, TS-X, and TS-Y

The stipple attribute of a graphic context contains a bitmap that is used to
prevent certain pixels in the destination of graphic operations from being
affected by tiling.  The tile attribute is a pixmap that is used to fill in
areas for graphic operations.  They are so named because copies of them are
laid out side by side to fill in the area.  The ts-x and ts-y attributes of
a graphic context are the coordinates of the origin for the stipple and tile
pixmaps.

The stipple and tile have the same origin.  This origin point is interpreted
relative to the origin of whatever destination drawable is specified in a
graphics request.  The stipple pixmap must have depth one and must have the
same root as the graphic context.  The tile pixmap must have the same root
and depth as the graphic context.  For stipple operations where the
fill-style is :stippled (but not :opaque-stippled) the stipple pattern is
tiled in a single plane and acts as an additional clip mask to be ANDed with
the clip-mask.  Any size pixmap can be used for stipple or tile, although
some sizes may be faster to use than others.

Specifying a pixmap for stipple or tile in a graphic context might or might
not result in a copy being made.  If the pixmap is later used as the
destination for a graphic operation, the change might or might not be
reflected in the graphic context.  If the pixmap is used both as the
destination for a graphic operation and as a stipple or tile, the results
are not defined.

Some displays have hardware support for tiling or stippling with patterns of
specific sizes.  Tiling and stippling operations that that restrict
themselves to those sizes may run much faster than such operations with
arbitrary size patterns.  CLX provides functions with which you can
determine the best size for stipple or tile.


(DEFUN gcontext-stipple (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES stipple)
           (TYPE pixmap stipple)))

Settable.

gcontext
        The graphic context whose stipple attribute is to be accessed.


(DEFUN gcontext-tile (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES tile)
           (TYPE pixmap tile)))

Settable.

gcontext
        The graphic context whose tile attribute is to be accessed.


(DEFUN gcontext-ts-x (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES ts-x)
           (TYPE int16 ts-x)))

Settable.

gcontext
        The graphic context whose ts-x attribute is to be accessed.


(DEFUN gcontext-ts-y (gcontext)
  (DECLARE (TYPE gcontext gcontext)
           (VALUES ts-y)
           (TYPE int16 ts-y)))

Settable.

gcontext
        The graphic context whose ts-y attribute is to be accessed.


(DEFUN query-best-stipple (width height drawable)
  (DECLARE (TYPE card16 width height)
           (TYPE drawable drawable)
           (VALUES best-width best-height)
           (TYPE card16 best-width best-height)))

(DEFUN query-best-tile (width height drawable)
  (DECLARE (TYPE card16 width height)
           (TYPE drawable drawable)
           (VALUES width height)
           (TYPE card16 best-width best-height)))

width
height  Specifies the width and height of the desired stipple or tile
        pattern.

drawable
        Specifies the drawable which you are interested in setting the
        stipple or tile for.

These functions return the best ("best" means the size that can be drawn
fastest) size or the stipple or tile for the screen that contains the
specified drawable.  The drawable indicates the screen and possibly the
window class and depth.  An input-only window cannot be specified as the
drawable for these functions.  The size is returned as width and height in
multiple values.


5.4.  Copying Graphic Contexts

CLX provides functions with which you can copy some or all attribute values
from one graphic context to another.  You might wonder why this isn't just
done using SETF.  The answer is that these functions request that the server
do the copy internally without sending the data back through the client
application.  This will generally be more efficient (particularly for things
like clip and dash lists).


(DEFUN copy-gcontext (src dst)
  (DECLARE (TYPE gcontext src dst)))

src     Specifies the graphic context from which the attribute values are
        to be copied.

dst     Specifies the graphic context to which the attributes values are to
        be copied.

This function copies all of the values of the attributes of the source
graphic context into the destination graphic context.  The source and
destination graphic contexts must have the same root and depth.


(DEFUN copy-gcontext-components (src dst &rest keys)
  (DECLARE (TYPE gcontext src dst)
           (TYPE LIST keys)))

src     Specifies the graphic context from which the attribute values are
        to be copied.

dst     Specifies the graphic context to which the attributes values are to
        be copied.

keys    The remaining arguments are keywords, of type gcontext-key, which
        specify which attributes of the graphic context are to be copied.


This function copies the values of the specified attributes of the source
graphic context to the destination graphic context.  The source and
destination graphic contexts must have the same root and depth.


5.5.  Destroying Graphic Contexts


(DEFUN free-gcontext (gcontext)
  (DECLARE (TYPE gcontext gcontext)))

gcontext
        The graphic context which is to be freed.

This function deletes the association between the assigned resource id and
the specified graphic context and then destroys the graphic context.  This
function destroys the specified graphic context as well as the shadow copy.


5.6.  Graphic Context Cache

CLX provides a set of functions that allow a programmer to exercise some
control the automatic graphic context caching mechanism.  This section
explains the use of the functions that interface to this feature.


(DEFUN force-gcontext-changes (gcontext)
  (DECLARE (TYPE gcontext gcontext)))

gcontext
        Specifies the graphic context whose delayed changes are to be sent.

This function forces any delayed changes to the specified graphic context to
be sent out to the server.


(DEFMACRO with-gcontext ((gcontext
                          &key arc-mode background cap-style clip-mask
                               clip-ordering clip-x clip-y dashes
                               dash-offset exposures fill-rule fill-style
                               font foreground function join-style
                               line-style line-width plane-mask stipple
                               subwindow-mode tile ts-x ts-y
              &allow-other-keys)
             &body body))

gcontext
        Specifies the graphic context whose components are to be temporarily
        altered.

:arc-mode
:background
:cap-style
:clip-mask
:clip-ordering
:clip-x
:clip-y
:dashes
:dash-offset
:exposures
:fill-rule
:fill-style
:font
:foreground
:function
:join-style
:line-style
:line-width
:plane-mask
:stipple
:subwindow-mode
:tile
:ts-x
:ts-y    These keyword arguments and associated values specify which graphic
        context components are be changed and their new values.  Any
        components not specified are left unmodified. See section
    5.1 creating graphics contexts for more information.

body    The body of code which will have access to the altered graphic
        context.

This macro changes the indicated graphic context components to the specified
values within the dynamic scope of the body (indefinite scope and dynamic
extent).  This will work on a per-process basis in a multiprocessing
environment.  The body is not surrounded by a with-display form.  If there
is no local cache for the specified graphic context or if some of the
component states are unknown, this function will do the save and restore by
creating a temporary graphic context and copying components to and from it
using copy-gcontext-components.





                  Chapter 6

             Graphics Resource Functions



6.1.  Colormaps and Colors

A colormap is a collection of color cells.  A color cell contains of a
triple of red, green, and blue values.  A pixel is an index into a colormap.
As each pixel is read out of display memory, its value is taken and used to
looked up a color cell in the colormap.  The values in the cell determine
what color is displayed on the screen.  On a multiplane display with a black
and white monitor (grayscale, but not color), these values may or may not be
combined to determine the brightness on the screen.

The introduction of color changes the view a programmer should take when
dealing with a bitmap display.  For example, when drawing, you write pixel
values, which are defined to be specific colors, rather than setting or
clearing bits.  The display hardware will impose limits which must be
comprehended, such as the number of significant bits in pixel values and the
number of simultaneously available colormaps.  Typically, an application
allocates color cells or sets of color cells in a colormap.  If the color
cells are read only, the pixel values for them may be shared among multiple
applications, since the RGB values for the cell cannot be changed.  If the
color cells are read/write, they are exclusively owned by the program, and
the contents may be changed at will.

Windows in CLX always have an associated colormap which provides a level of
indirection between pixel values and the color displayed on the screen.
Because colormaps are associated with windows, X will support displays with
multiple colormaps and, indeed, different types of colormaps.  However, many
of the hardware displays used today have a single colormap, so CLX functions
are written to encourage sharing of colormap entries between applications.
If there are not sufficient colormap resources in the display, some windows
may not be displayed in their true colors.  A window manager can set which
windows are displayed in their true colors if more than one colormap is
required for the color resources the applications are using.


6.1.1.  Color Functions


A color is a structure containing a triple of red, green, and blue values
that define a specific visible color.  It is a representation of a set of
values that could be stored in a color cell.  Although the following RGB
oriented functions are provided for colors the intention is that other (IHS,
YIQ, and CYM) interfaces could also exist.  Note that CLX explicitly uses a
different spectrum representation than what is actually transmitted in the
protocol.


(DEFUN make-color (&key (blue 1.0) (green 1.0) (red 1.0) &allow-other-keys)
  (DECLARE (TYPE rgb-val blue green red)
       (VALUES color?)
       (TYPE color color?)))

:blue
:green
:red    Keyword values that specify the saturation for each primary that
        will be used to define the newly created color.  They each default
        to a value of 1.0 indicating full saturation.

This function creates, initializes and returns a new color structure with
the specified values for the red, green, and blue levels.


(DEFUN color-p (color)
  (DECLARE (TYPE T color)
           (VALUES color?)
           (TYPE boolean color?)))

color    The data object which is to be tested to see if it is a color.

This function returns non-null if the argument is a color and NIL otherwise.


(DEFUN color-blue (color)
  (DECLARE (TYPE color color)
           (VALUES blue-saturation)
       (TYPE rgb-val blue-saturation)))

Settable.

color    Specifies the color whose blue component is to be returned.

The color-blue function returns the value for the blue level in the
specified color structure.


(DEFUN color-green (color)
  (DECLARE (TYPE color color)
           (VALUES green-saturation)
       (TYPE rgb-val green-saturation)))

Settable.

color    Specifies the color whose green component is to be returned.

The color-green function returns the value for the green level in the
specified color structure.


(DEFUN color-red (color)
  (DECLARE (TYPE color color)
       (VALUES red-saturation)
       (TYPE rgb-val red-saturation)))

Settable.

color    Specifies the color whose green component is to be returned.

The color-red function returns the value for the red level in the specified
color structure.


(DEFUN color-rgb (color)
  (DECLARE (TYPE color color)
       (VALUES red green blue)
       (TYPE rgb-val red green blue)))

color    Specifies the color whose red, green, and blue components are to be
        returned.

This function returns as multiple values the values for the red, green, and
blue levels in the specified color structure.


6.1.2.  Color Cell Functions


A color cell is an entry in a colormap that is indexed by a pixel value and
contains a red, green, blue triple defining a particular color.  Allocating
color cells is the way that a client ensures that the colors that it needs
are in the colormap.  It is also how a client determines the pixel value for
a particular color.  Color cells may be allocated as read-only, which allows
them to be shared among clients, or read/write, which gives exclusive use to
the allocating client.

CLX provides functions to retrieve the contents of color cells, to allocate
color cells, and to deallocate color cells.  On a screen that either cannot
load the colormap or cannot have a fully independent colormap, only certain
kinds of allocations may work.


(DEFUN alloc-color (colormap color)
  (DECLARE (TYPE colormap colormap)
       (TYPE (OR stringable color) color)
       (VALUES pixel screen-color exact-color)
       (TYPE card32 pixel)
       (TYPE color screen-color exact-color)))

colormap
        Specifies the colormap in which the color cell is to be allocated.

color    May either be a color structure or the name of a color specifying
    the color which is to be allocated in the specified colormap.

If the color argument is a color structure then this function allocates a
read-only colormap entry corresponding to the closest RGB values provided by
the hardware.  If the color argument is a color name then it is looked up
with respect to the screen of the specified colormap and the color object
associated with that name is used to allocated a read-only colormap entry as
described above.  The name should use the ISO Latin-1 encoding, and
uppercase and lowercase do not matter.

The values returned by this function are the pixel value for the color cell
which was allocated, the screen-color which is the actual contents of the
allocated color cell, and the exact-color which is the actual definition for
the specified color.  If the color argument is a color structure then it is
always returned for the exact-color return value.


(DEFUN lookup-color (colormap name)
  (DECLARE (TYPE colormap colormap)
       (TYPE stringable name)
       (VALUES screen-color exact-color)
       (TYPE color screen-color exact-color)))

colormap
        Specifies the colormap from which the color definition is to be
        retrieved.

name    Specifies the name of a color whose definition is to be returned

This function looks up the specified color with respect to the screen of the
specified colormap.  It returns both the screen-color which is the closest
color that can be provided by the hardware for the visual type of the
specified colormap, and the exact-color which is the actual definition for
the named color.  The name should use ISO Latin-1 encoding, and uppercase
and lowercase do not matter.


(DEFUN query-colors (colormap pixels &key (result-type 'LIST))
  (DECLARE (TYPE colormap colormap)
       (TYPE SEQUENCE pixels)
       (TYPE T :result-type)
       (VALUES colors)
       (TYPE (SEQUENCE color) colors)))

colormap
        Specifies the colormap whose color cells are to be queried.

pixels    A sequence of pixels values that specifies the individual color
        cells whose values are to be retrieved.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequence should be created to
        return the contents of the specified color cells.  The default is to
        return them in a list.

This function returns a sequence of color structures which hold the contents
of the requested color cells from the specified colormap.  The values
returned for unallocated color cells are undefined.


6.1.3.  Colormap Functions


Colormaps are local to a particular screen and a screen always has a default
colormap.  The default colormap is typically set up by the by the server
when the connection is made.  Client programs are free to allocate and free
cells out of this colormap but writing applications which monopolize color
resources is highly discouraged.

Although a colormap consists of a set of color cells, the values of these
color cells which may or may not be defined values.  The colormap associated
with a window is used to display the contents of the window.  Applications
should not directly modify any part of the colormap structure, except where
the elements are stated to be settable.  The other elements should be
considered read-only, although they may change as the result of other
operations on the colormap.


(DEFUN colormap-equal (colormap-1 colormap-2)
  (DECLARE (TYPE colormap colormap-1 colormap-2)))

colormap-1
colormap-2
    The colormap structures that are to be compared for equality.

This function returns non-null if the two arguments are equivalent colormap
structures and NIL if they are not.


(DEFUN colormap-id (colormap)
  (DECLARE (TYPE colormap colormap)
       (VALUES id)
       (TYPE resource-id id)))

colormap
        Specifies the colormap whose resource id is to be accessed.

This function returns the unique id that has been assigned to the specified
colormap by the server.


(DEFUN colormap-p (colormap)
  (DECLARE (TYPE colormap colormap)
       (VALUES map-p)
       (TYPE boolean map-p)))

colormap
        The data object which is to be tested to see if it is a colormap.

This function returns non-null if the argument is a colormap and NIL
otherwise.


6.1.3.1  Creating Colormaps


CLX provides a function for creating new colormap structures.  These CLX
structures should not be confused with the physical colormaps in the display
hardware.


(DEFUN create-colormap (visual window &optional alloc-p)
  (DECLARE (TYPE card29 visual)
       (TYPE window window)
       (TYPE boolean alloc-p)
       (VALUES colormap)
       (TYPE colormap colormap)))

visual    Specifies the id for a visual type supported for the screen on which
        the specified window is defined.  It is an error to specify a visual
        type which is not one supported by the screen.

window    Specifies the window whose display the colormap is be associated
        with.

alloc-p    An optional parameter that specifies whether or not the color cells
        in the newly created colormap are to be pre-allocated.  The default
        is NIL which indicates that the colormap will initially have no
        allocated color cells.

This function creates a colormap of the specified visual type for the
display on which the window resides.  It is an error if the visual type is
not one supported by the display.  The initial values of the color cells in
the colormap are undefined for visual types of class :gray-scale,
:pseudo-color, or :direct-color.  For visual types of class :static-gray,
:static-color, or :true-color the color cells will have defined initial
values that are specific to the visual type, but these values are not
defined by the X protocol.

When creating a colormap for a visual type of class :static-gray,
:static-color, or :true-color the alloc-p argument must be specified as NIL.
It is an error otherwise.

If alloc-p is specified as NIL and the visual type is of class :gray-scale,
:pseudo-color, or :direct-color then the colormap initially has no allocated
color cells and clients are free to allocate them.  If alloc-p is specified
as T then the entire colormap is "allocated" as writable and the initial
values of all color cells are undefined.  For :gray-scale and :pseudo-color,
the effect is as if an alloc-color request returned all pixel values from
zero to N-1, where N is the colormap-entries value from the specified visual
type.  For :direct-color, the effect is as if an alloc-color-planes request
returned a pixel value of zero and red-mask, green-mask, and blue-mask
values containing the same bits as the corresponding masks in the specified
visual type.  However, in all cases, none of these entries can be freed with
free-colors.


(DEFUN copy-colormap-and-free (colormap)
  (DECLARE (TYPE colormap colormap)
       (VALUES new-colormap)
       (TYPE colormap new-colormap)))

colormap
        Specifies the source colormap that is to be duplicated and freed.

This function creates and returns a new colormap of the same visual type and
for the same screen as the specified source colormap.  It then moves all of
the calling client's allocations from the source colormap to the new
colormap, keeping their values and read-only or writable characteristics
intact, and frees those allocations.  The other allocatable color cells or
planes in the new colormap are left undefined.

If the specified source colormap was created by the calling client with its
color cells all pre-allocated then the new colormap is also created with
pre-allocated color cells.  In this case, the values for all color cells are
copied from the source colormap, and then all color cells in the source
colormap are freed.  If the specified source colormap was not created by the
calling client with pre-allocated color cells, then the only allocations
which are copied are those color cells and planes that have been allocated
by the client using the alloc-color, alloc-named-color, alloc-color-cells,
or alloc-color-planes functions (see section 6.??), and which have not since
been freed.


6.1.3.2.  Installing Colormaps


A colormap is installed if the X server has loaded it into the display
hardware such that it can be used during display refresh to determine colors
on a screen.  Depending on hardware limitations, one or more colormaps may
be installed at one time, such that windows associated with those maps
display with the correct colors.

At any time, there is a subset of the installed colormaps called the
"required list".  The length of the required list is at most M, where M is
the minimum number of installed colormaps specified for the screen in the
connection setup.  The required list is maintained as follows.  When a
colormap is explicitly installed it is added to the head of the list, and
the list is truncated at the tail, if necessary, to keep the length of the
list to at most M.  When a colormap is explicitly uninstalled and it is in
the required list, it is removed from the list.  A colormap is not added to
the required list when it is installed implicitly by the server, and the
server cannot implicitly uninstall a colormap that is in the required list.
Initially the default colormap for a screen is installed (but is not in the
required list).


(DEFUN install-colormap (colormap)
  (DECLARE (TYPE colormap colormap)))

colormap
        The colormap that is to be installed.

This function makes the specified colormap an installed colormap and adds it
to the required list for its screen.  All windows associated with this
colormap immediately display with true colors.  As a side-effect, additional
colormaps might be implicitly installed or uninstalled by the server.  Which
other colormaps get installed or uninstalled is server-dependent, except
that the colormaps on the required list must remain installed.

If the specified colormap is not already installed, a colormap-notify event
is generated on every window which has this colormap associated with it.  In
addition, for every other colormap that is implicitly installed or
uninstalled as a result of this operation, a colormap-notify event is
generated on every window referencing that colormap.


(DEFUN installed-colormaps (window &key (result-type 'list))
  (DECLARE (TYPE window window)
       (TYPE type :result-type)
       (VALUES colormaps)
       (TYPE (SEQUENCE colormap) colormaps)))

window    Specifies the window whose screen is to be queried for its currently
        installed colormaps.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequence should be created to
        return the installed colormaps for the specified screen.  The
        default is to return them in a list.

This function returns a sequence of colormap structures which are the
currently installed colormaps for the screen of the specified window.  The
order of the colormaps is not significant, and there is no explicit
indication of which colormaps are required.


(DEFUN uninstall-colormap (colormap)
  (DECLARE (TYPE colormap colormap)))

colormap
    The colormap that is to be uninstalled.

If the specified colormap is on the required list for its screen then it is
removed from the list.  As a side-effect, the colormap might be uninstalled,
and additional colormaps may be implicitly installed or uninstalled.  Which
colormaps get installed or uninstalled is server-dependent, except that the
colormaps that are still on the required list must remain installed.

If colormap becomes uninstalled, a colormap-notify event is generated on
every window which has colormap associated with it.  In addition, for every
other colormap that is implicitly installed or uninstalled as a result of
this operation, a colormap-notify event is generated on every window
referencing that colormap.


6.1.3.3.  Destroying Colormaps


(DEFUN free-colormap (colormap)
  (DECLARE (TYPE colormap colormap)))

colormap
    Specifies the colormap which is to be freed.

This function deletes the association between the assigned resource id and
the specified colormap and then destroys the colormap.  However, this
function has no effect on a default colormap for a screen.  If the colormap
is installed for a screen, it is uninstalled (see section 6.4).  If a window
has the colormap associated with it then the colormap for the window is
changed to NIL, and a colormap-notify event is generated.  The colors
displayed for a window with a colormap of NIL are not defined by the
protocol.


6.1.4  Color cells and planes


(DEFUN alloc-color-cells (colormap colors
              &key (planes 0) contiguous-p (result-type 'LIST))
  (DECLARE (TYPE colormap colormap)
       (TYPE card16 colors :planes)
       (TYPE boolean :contiguous-p)
       (TYPE type :result-type)
       (VALUES pixels plane-masks)
       (TYPE (SEQUENCE pixel) pixels)
       (TYPE (SEQUENCE mask32) plane-masks)))

colormap
        Specifies the colormap in which the color cells are to be allocated.

colors    Specifies the number of color cells to allocate.  This value must be
        greater than zero.

:planes    A keyword argument, whose value must be zero or greater, that
        specifies the number of planes to allocate.  The default is zero (do
        not allocate any planes).

:contiguous-p
        Specifies a boolean value.  You pass the value 1 if the planes must be
        contiguous or the value 0 if the planes do not need to be contiguous.

:result-type
        A keyword argument, that is a valid type specifier for a sub-type of
        SEQUENCE, indicating what kind of sequences should be created to
        return the pixel values of the allocated color cells and the masks
        for the allocated color planes.  The default is to return them in a
        list.

The alloc-color-cells function allocates read/write color cells.  The number
of colors must be positive and the number of planes nonnegative.  If colors
and planes are requested, then pixel and masks are returned.  No mask will
have any bits in common with any other mask or with any of the pixels.  By
ORing together masks and pixels, C*(2^P) distinct pixels can be produced; all
of these are allocated writable by the request.  For :gray-scale or
:pseudo-color, each mask will have exactly one bit, and for :direct-color each
will have exactly three bits.  If contiguous is True, then if all masks are
ORed together, a single contiguous set of bits will be formed for :gray-scale
or :pseudo-color, and three contiguous sets of bits (one within each pixel
subfield) for :direct-color.  The RGB values of the allocated entries are
undefined.


(DEFUN alloc-color-planes (colormap colors &key (reds 0) (greens 0) (blues 0)
                        contiguous-p
                        (result-type 'list))
  (DECLARE (TYPE colormap colormap)
       (TYPE card16 colors :reds :greens :blues)
       (TYPE boolean :contiguous-p)
       (TYPE type :result-type)
       (VALUES (SEQUENCE pixel) red-mask green-mask blue-mask)
       (TYPE card16  red-mask green-mask blue-mask)))

colormap
        Specifies the colormap ID for whose planes will be allocated.

colors    A positive number of pixel values that are to be returned by the pixel
    list.

:reds
:greens
:blues    Specify the number of red, green, and blue colors (shades).  The
    value you pass must be non-negative.

:contiguous-p
        T if the planes must be contiguous or NIL if the planes do not need to
        be contiguous.

:result-type
    The form in which the results are to be returned. The default is list.


The specified number of colors must all be positive while reds, greens, and
blues must be non-negative.  If colors (C), reds (R), greens (R), and blues
(B) are requested, then the pixel sequence (which defaults to a list) is
returned along with the red-mask, green-mask, and blue-mask.  If contiguous is
True, then each mask will have a contiguous set of bits.  All mask bits are
mutually exclusive; that is to say that no mask will have any bits set in
common with any other mask.  For :direct-color, each mask will lie within the
corresponding pixel subfield.  By ORing together subsets of masks with pixels,
C*(2^(R+G+B)) distinct pixels can be produced; all of these are allocated by
the request.  The initial RGB values of the allocated entries are undefined.
In the colormap there are only C*(2^R) independent red entries, C*(2^G)
independent green entries, and C*(2^B) independent blue entries.  This is also
true for :pseudo-color.  When the colormap entry for a pixel value is changed
using store-colors or store-named-color, the pixel is decomposed according to
the masks and the corresponding independent entries are updated.



6.2    Manipulating Colors


CLX provides functions with which you can allocate color values for pixels
that you need to display and can deallocate them when they are no longer
needed.  There are two ways of allocating color cells: explicitly as read only
entries by pixel value or read/write, where you can allocate a number of color
cells and planes simultaneously.  The read/write cells you allocate do not
have defined colors until set with store-color or store-colors.

The query-colors returns the red, green, and blue color values stored in the
specified colormap.  The values returned for an unallocated entry are
undefined.

To determine the color names, the X server uses a color data base.  Although
you can change the values in a read/write color cell that is allocated by
another application, this is considered "anti-social" behavior.


(DEFUN store-color (colormap pixel spec &key (red-p T) (green-p T) (blue-p T))
  (DECLARE (TYPE colormap colormap)
       (TYPE pixel pixel)
       (TYPE (OR stringable color) spec)
       (TYPE boolean :red-p :green-p :blue-p)))

colormap
    Specifies the colormap that receives the color.

pixel    Specifies the pixel index into the colormap.

spec    Specifies whether the color of the referenced pixel is referred to by
    stringable name (i.e. "red"") or an RGB color structure.
:red-p
:green-p
:blue-p    Are optional keywords that when NIL, cause that color (red-p, etc.) to
        be ignored when updating colormap.  However, if spec is a stringable
        then the keywords are ignored.


Store-color changes the colormap pixel index to the color described in spec.
Spec may be either an RGB color structure or a stringable.  When spec is a
stringable, the protocol does not specify id the stringables are first
resolved and then a single store-colors protocol request is issued, or whether
multiple store-colors protocol requests are issued.  The keywords: red-p,
green-p, and blue-p indicate which color components of pixel should actually
be changed.  If the colormap is an installed map for its screen, the changes
are visible immediately.



(DEFUN store-colors (colormap specs &key (red-p T) (green-p T) (blue-p T))
  (DECLARE (TYPE colormap colormap)
       (TYPE (repeat-seq (pixel pixel)
                 ((OR stringable color) color)) specs)
       (TYPE boolean :red-p :green-p :blue-p)))

colormap
    Specifies the colormap in which the colormap pixel entries presented
    in specs will be written upon.

specs    Specifies 2-tuple list of of the form ((pixel# color)..) where pixel is
        the pixel number to get the color, and color is either a stringable
    name (i.e. "red") or an RGB color structure.
:red-p
:green-p
:blue-p    Are optional keywords that when NIL, cause that color (red-p, etc.) to
        be ignored when updating colormap.  However, if specs contains a
        stringable then the keywords are ignored.


Store-colors changes multiple colormap pixel indices to the colors described
in spec.  Spec is a sequence of a paired list of pixel-index and color-spec of
the form ((pixel#,spec)...) As in store-color, spec may be either an RGB color
structure or a stringable.  When spec is a stringable, the protocol does not
specify if the stringables are first resolved and then a single store-colors
protocol request is issued, or whether multiple store-colors protocol requests
are issued.  The keywords: red-p, green-p, and blue-p indicate which color
components for all of pixels described in spec should actually be changed.  If
the colormap is an installed map for its screen, the changes are visible
immediately.


To emulate an XLib StoreNamedColor request use store-color or store colors
with the color spec as a stringable.



(DEFUN free-colors (colormap pixels &OPTIONAL (plane-mask 0))
  (DECLARE (TYPE colormap colormap)
       (TYPE (SEQUENCE pixel) pixels)
       (TYPE pixel plane-mask)))

colormap
    Specifies the colormap on which pixels will be cleared.

pixels    specifies a sequence (usually of integers) of colormap pixel indices
    to free.

plane-mask
    Specifies the planes you want to free.

The free-colors function frees the cells in colormap represented by pixels.
Planes should not have any bits in common with any of the indices in pixels.
The set of all pixels is produced by ORing together subsets of the planes
argument with the pixels.  The request frees all of these pixels that were
allocated by the client using alloc-color, alloc-colors, alloc-color-cells,
and alloc-color-planes.  Note that freeing an individual pixel obtained from
alloc-color-planes may not actually allow it to be reused until all of its
"related" pixels are also freed.

All specified pixels that are allocated by the client in colormap are freed,
even if one or more pixels produce an error.  An error is generated if a
specified pixel is not a valid index into colormap.  Another error is
generated if a specified pixel is not allocated by the client (that is, is
unallocated or is only allocated by another client).  If more than one pixel
is in error, the one reported is arbitrary.


6.3.    Pixmaps


A "pixmap" is a three dimensional array of bits.  A pixmap is normally thought
of as a two dimensional array of pixels, where each pixel can be a value from
0 to 2N-1, where N is the depth (z axis) of the pixmap.  A pixmap can also be
thought of as a stack of N bitmaps.  CLX provides functions with which you
can: create or free a pixmap, test if an object is a pixmap, test if two
pixmap objects are equal, or return the pixmap resource-ID from a pixmap
object.

Pixmaps can only be used on the screen on which they were created.  Pixmaps
are off-screen resources that are used for a number of operations.  A bitmap
is a single bit pixmap.  These include defining cursors as tiling patterns or
as the source for certain raster operations.  Most graphic requests can
operate either on a window or on a pixmap.


(DEFUN create-pixmap (&key width height depth drawable)
  (DECLARE (TYPE card16 :width :height)
           (TYPE card8 :depth)
           (TYPE drawable :drawable)
           (VALUES pixmap?)
       (TYPE pixmap pixmap?)))

:width
:height  Specify the width and height.  These dimensions define the width and
        height of the pixmap.  The values you pass must be nonzero.

:depth   Specifies the depth of the pixmap.  The depth must be supported by
        the root of the specified drawable.

:drawable
        Specifies the drawable which you are interested in setting the
        stipple or tile for.


The create-pixmap function creates a pixmap of the width, height, and depth
you specify and assigns the pixmap ID (PID) to it.  It is valid to pass a
window whose class is Input-Only to the drawable argument.  The width and
height arguments must be nonzero.


(DEFUN free-pixmap (pixmap)
  (DECLARE (TYPE pixmap pixmap)))

pixmap  Specifies the pixmap to be freed.

The Free-Pixmap function first deletes the association between the pixmap ID
and the pixmap.  Then, the X server frees the pixmap storage when no other
resources reference it.  The pixmap should never be referenced again.
Free-Pixmap can generate a Bad-Pixmap error.


(DEFUN pixmap-p (pixmap)
   (DECLARE (TYPE pixmap pixmap)
        (VALUES boole)
        (TYPE boolean boole)))

pixmap    A three dimensional array of bits which is tested as a pixmap object.

This function returns a boolean; T if the argument is a pixmap object and NIL
otherwise.


(DEFUN pixmap-id (pixmap)
   (DECLARE (TYPE pixmap pixmap)
        (VALUES id)
        (TYPE resource-id id)))

pixmap    A three dimensional array of bits whose ID is returned.

This function returns the unique resource-id that has been assigned to the
specified pixmap by the server.


(DEFUN pixmap-equal (pixmap-1 pixmap-2)
   (DECLARE (TYPE pixmap pixmap-1 pixmap-2)))

pixmap-1
pixmap-2
    A three dimensional array of bits to be tested.

This function returns T if the two arguments are equivalent pixmaps and NIL if
they are not.



****----preliminary section designations

    6.4. Manipulating Graphics Context/State

    6.5. Using GC Convenience Routines

    6.5.1. Setting the Foreground, Background, Plane Mask, or Function

    6.5.2. Setting the Line Attributes and Dashes

    6.5.3. Setting the Fill Style and File Rule

    6.5.4. Setting the Fill Tile and Stipple

    6.5.5. Setting the Current Font

    6.5.6. Setting the Clip Region

    6.5.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure





                  Chapter 7

                             Graphic Operations


Once you have connected to the X server, you can use CLX functions to
perform graphic operations on drawables.  If the same drawable and graphic
context is used, CLX batches back to back calls to draw-point, draw-line,
draw-rectangle, draw-arc, and friends to speed server processing.

This chapter describes the CLX functions that you may use to:

o    Operate on areas and planes

o    Draw points

o    Draw lines

o    Draw rectangles

o    Draw arcs


7.1.  Area and Plane Operations

CLX provides functions with which you can clear an area or an entire window
to the background.  Because pixmaps do not have backgrounds, they cannot be
filled by using the functions described in this section.  Instead, you
should use draw-rectangle, which sets the pixmap to a known value.  See
Section 7.4  for information on draw-rectangle.


(DEFUN clear-area (window &key (x 0) (y 0) width height exposures-p)
  (DECLARE (TYPE window window)
           (TYPE int16 :x :y)
           (TYPE (OR NULL card16) :width :height)
           (TYPE boolean :exposures-p)))

window  The window which is to have an area cleared.

:x
:y    Specify the upper-left hand corner of the area to be cleared.  These
        coordinates are relative to the window origin.

:width  The width of the area to clear or NIL to clear to the remaining
        width of the window.

:height The height of the area to clear or NIL to clear to the remaining
        height of the window.

:exposures-p
        Specifies if exposure events should be generated for the affected
        areas.

This function paints a rectangular area in the specified window with the
background pixel or pixmap of the window.  The x and y coordinates are
relative to the window origin, and specify the upper left corner of the
rectangular area that is to be cleared.  A NIL or zero value for height or
width clears the remaining area (height-y or width-x).  If the window has a
defined background tile, the rectangle is tiled by using a plane-mask of all
ones and a function of :copy.  If the window has background :none, the
contents of the window are not changed.  In either case, if exposures-p is
non-null, then one or more exposure events are generated for regions of the
rectangle that are either visible or are being retained in a backing store.

To clear the entire area in a specified window, use (clear-area window).


(DEFUN copy-area (src gcontext src-x src-y width height dst dst-x dst-y)
  (DECLARE (TYPE drawable src dst)
           (TYPE gcontext gcontext)
           (TYPE int16 src-x src-y dst-x dst-y)
           (TYPE card16 width height)))

src    Specifies the source drawable from which to copy the area from.

gcontext
        The graphic context to use during the copy operation.

src-x
src-y   Specify the x and y coordinates of the upper left corner of the area
        in the source drawable which is to be copied.  These coordinates are
        relative to the source drawables origin.

width
height  The width and height of the area being copied.  These apply to both
    the source and destination areas.

dst     Specifies the destination drawable that is to be copied to.

dst-x
dst-y   Specify the x and y coordinates of the upper left corner of the area
        in the destination drawable which is to be copied to.  These
        coordinates are relative to the destination drawables origin.

This function copies the specified rectangular area from the source drawable
to the specified rectangular area of the destination drawable, combining
them as specified in the supplied graphic context.  The x and y coordinates
are relative to their respective drawable origin, with each pair specifying
the upper left corner of the area.

If either regions of the source area are obscured and have not been retained
in backing store or regions outside the boundaries of the source drawable
are specified, those regions are not copied.  Instead, the following occurs
on all corresponding destination regions that are either visible or are
retained in backing store.  If the destination rectangle is a window with a
background other than :none, these corresponding regions of the destination
are tiled, using plane-mask of all ones and function of BOOLE-1 (copy), with
that background.  Regardless of tiling or whether the destination is a
window or a pixmap, if the exposures attribute of the graphic context is
:on, then graphics-expose events for all corresponding destination regions
are generated.  If exposures is :on but no regions are exposed, a no-expose
event is generated.  Note that by default, exposures is :on on in new
graphic contexts.  See chapter 5 for further information.


(DEFUN copy-plane (src gcontext plane src-x src-y width height dst dst-x
           dst-y)
  (DECLARE (TYPE drawable src dst)
           (TYPE gcontext gcontext)
           (TYPE pixel plane)
           (TYPE int16 src-x src-y dst-x dst-y)
           (TYPE card16 width height)))

src     Specifies the source drawable from which to copy the area from.

gcontext
        The graphic context to use during the copy operation.

plane   Specifies the bit-plane of the source drawable that is to be copied.
        Exactly one bit must be set.

src-x
src-y   Specify the x and y coordinates of the upper left corner of the area
        in the source drawable which is to be copied.  These coordinates are
        relative to the source drawables origin.

width
height  The width and height of the area being copied.  These apply to both
    the source and destination areas.

dst     Specifies the destination drawable that is to be copied to.

dst-x
dst-y   Specify the x and y coordinates of the upper left corner of the area
        in the destination drawable which is to be copied to.  These
        coordinates are relative to the destination drawables origin.

The copy-plane function uses a single bit plane of the specified rectangular
area of the source drawable along with the specified graphic context to
modify the specified rectangle area of the destination drawable.  The
drawables specified by the src and dst arguments must have the same root but
need not have the same depth.

Effectively, this operation forms a pixmap of the same depth as dst and with
a size specified by the source area.  It then uses the foreground and
background from the graphic context (foreground everywhere the bit-plane in
src contains a one bit, background everywhere the bit-plane in src contains
a zero bit) and the equivalent of a copy-area operation is performed with
all the same exposure semantics.  This can also be thought of as using the
specified region of the source bit-plane as a stipple with a fill-style of
:opaque-stippled for filling a rectangular area of the destination.


7.2.  Drawing Points

The Draw-Point and Draw-Points functions make use of the following
graphic contexts: function, plane-mask, foreground, subwindow-mode, clip-x, clip-y,
clip-ordering, clip-region and clip-mask.

The Draw-Point function uses the foreground pixel and function components of
the graphic context to draw a single point into the specified drawable,
while Draw-Points draws multiple points into the specified drawable.  These
functions are not affected by the tile or stipple in the graphic context.


(DEFUN draw-point (drawable gcontext x y)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE int16 x y)))


drawable
        Specifies the drawable which will get the point.

gcontext
        Specifies the graphic context.

x
y       Specifies the x and y coordinates where you want the
        point drawn.


When using Draw-Point, you simply specify the x and y coordinates where you
want the point drawn.  Draw-Point then combines the foreground pixel in the
graphic context with the pixel in the drawable.  The point specified by the x and y
coordinates is always relative to the drawables origin.



(DEFUN draw-points (drawable gcontext points &optional relative-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE point-seq points)
           (TYPE boolean relative-p)))

drawable
        Specifies the drawable which the list of points are to
        be drawn upon.

gcontext
        Specifies the graphic context in which the points are
        to be drawn.

points  A list of points to be drawn in the the order listed.
        The first point is always relative to the drawables origin; if
        relative-p, the rest of the points are drawn relative to the
        previous point, else they are drawn relative to the origin of
        drawable.

relative-p
        specifies the coordinate mode used for drawing the pixels either
        relative to the origin or the previous point.


Draw-Points combines the foreground pixels in the graphic context with the pixels
at each point in the drawable.  The points are drawn in the order listed.

Draw-Points requires a mode argument, relative-p, that indicates whether the
points are relative to the drawables origin or to the previous point.  In
either case, The first point is always relative to the drawables origin; the
rest of the points are relative either to the drawables origin or to the
previous point, depending on the value of relative-p.


7.3.  Drawing Lines

All three functions: Draw-Line, Draw-Lines, and Draw-Segments use these
graphic context components: function, plane-mask, line-width, line-style,
cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
clip-mask.  The Draw-Lines function also uses the join-style graphic
context component.  All three functions use these graphic context
mode-dependent components: foreground, background, tile, stipple,
ts-x-origin, ts-y-origin, dash-offset, and dash-list.  See the general
discussion under create-gcontext in Section 5.1.


(DEFUN draw-line (drawable gcontext x1 y1 x2 y2 &optional relative-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE int16 x1 y1 x2 y2)
           (TYPE boolean relative-p)))

drawable
        Specifies the drawable which is to get the line.

gcontext
        Specifies the graphic context under which the line will be drawn.

x1
y1
x2
y2      Specifies the points used to connect the line.  Thus, Draw-Line
        draws a line connecting point x1, y1 to point x2, y2.

relative-p
        specifies the coordinate mode used for drawing the line either
        relative to the origin or the previous point.  In either case, the
        first point is always drawn relative to the origin of the drawable.


(DEFUN draw-lines (drawable gcontext points &key relative-p fill-p (shape :complex))
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE point-seq points)
           (TYPE boolean :relative-p :fill-p)
           (TYPE (MEMBER :complex :non-convex :convex) :shape)))

drawable
        Specifies the drawable which is to receive the poly lines.

gcontext
        Specifies the graphic context under which the lines will be drawn.


points  Specifies a list of points that define the lines which will be
        drawn.  The points are either relative to the origin or the previous
        point, depending on the value of relative-p.

:relative-p
        Specifies the coordinate mode as related to the origin, or as
        relative to the previous point.  In either case, the first point is
        always drawn relative to the origin.

:fill-p    When true, a filled polygon is drawn instead of a polyline.

:shape    is a hint that allows the server to use the most efficient area fill
    algorithm. Shape may be either :convex :non-convex or :complex.


Draw-lines draws poly lines between each pair of points in the points list.
The lines are drawn in the order listed and join correctly at all
intermediate points.  The Join-style graphic context is used to define the type of
joint to use.  When the first and last points coincide the first and last
lines also join correctly to produce a hollow polygon.

When relative-p is true, the first point is always relative to the
drawables origin; the rest are relative to the previous point.  When
relative-p is NIL, the rest of the points are drawn relative to the
drawables origin.

When :fill-p is True, the polygon defined by the points list in points is to
be filled.  The :shape keyword provides the server with a hint as to how to
best approach the fill operation.  :Shape may be either :complex (by default),
:convex, or non-convex.

The :convex operand is the simplest type of area and the fastest to fill.  A
fill area is convex if every straight line connecting any two interior points
is entirely inside the area.  For example, triangles and rectangles are convex
polygons.

The :non-convex operand is for filling an area that is not convex and is also
not self-intersecting.  Filling this type of area is harder than filling a
convex area, but easier than filling one that is self-intersecting.  For
example, the shape of the letter "T" is non-convex and non-self-intersecting.

The :complex operand is the most general (and therefore the hardest) type of
fill area.  A complex fill area may be non-convex and self-intersecting.  For
example, draw the outline of a bow tie, without lifting your pencil or tracing
over an edge twice.  This shape is non-convex and intersects itself at the
"knot" in the middle.

Note: unless you are sure that a shape is :convex or :non-convex, it should
always be drawn as a :complex shape.  If :convex or :non-convex is specified
incorrectly, the graphic result is undefined.


(DEFUN draw-segments (drawable gcontext segments)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE seg-seq segments)))

drawable
        Specifies the drawable which will receive the line segments.

gcontext
        Specifies the graphic context under which the line segments will be
        drawn.

segments
        Specifies the points list from which to draw the segments.


The draw-segments function uses the components of the specified graphic
context to draw multiple, but not necessarily connected lines.  For each
segment, draw-segments draws a line between (x1, y1) and (x2, y2).  The
lines are drawn in the order listed in the Segments variable.  Unlike
draw-lines above, no joining is performed at coincident end points For any
given line, no pixel is drawn more than once.  If lines intersect, then the
intersecting pixels are drawn multiple times.


7.4.  Drawing Rectangles


The Draw-Rectangle and Draw-Rectangles functions draw hollow or filled
outlines of the specified rectangle or rectangles as if a five-point
PolyLine were specified each rectangle:

        [x,y,] [x+width,y] [x+width,y+height] [x,y+height] [x,y]

Draw-Rectangle and Draw-Rectangles use these graphic context components:
function, plane-mask, line-width, line-style, join-style, fill-style,
subwindow-mode, clip-x, clip-y, and clip-mask.  Both functions also use
these graphic context mode-dependent components: foreground, background,
tile, stipple, ts-x-origin, ts-y-origin, dash-offset, and dash-list.  See
the discussion under create-gcontext in Chapter 5.


(DEFUN draw-rectangle (drawable gcontext x y width height &optional fill-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE int16 x y)
           (TYPE card16 width height)
           (TYPE boolean fill-p)))

drawable
        Specifies the drawable which will receive the rectangle.

gcontext
        Specifies the graphic context under which the rectangle will be
        drawn.

x y     Specifies the x and y coordinates that define the upper left corner
        of the rectangle.  The coordinates are relative to the windows
        origin.

width
height  Specify the width and height that define the outline of
        the rectangle.

fill-p  Specified whether the rectangle will be filled or hollow.


(DEFUN draw-rectangles (drawable gcontext rectangles &optional fill-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE rect-seq rectangles)
           (TYPE boolean fill-p)))


drawable
        Specifies the drawable which will receive the rectangles.

gcontext
        Specifies the graphic context under which the rectangle will be
        drawn.

rectangles
        a LIST of rectangles specifying the upper left corner
        X and Y, width and height of the rectangles to be drawn.

fill-p  Specified if the rectangles are to be filled or not.


For the specified rectangle or rectangles, no pixel is drawn more than once.
The x and y coordinates of each rectangle are relative to the drawables
origin and define the upper left corner of the rectangle.  Draw-Rectangles
draws the rectangles in the order listed in the array.  If rectangles
intersect, the intersecting pixels are drawn multiple times.


7.5.  Drawing Arcs

Draw-Arc draws a single circular or elliptical arc, while Draw-Arcs draws
multiple circular or elliptical arcs.  Draw-Arc and Draw-Arcs use these
graphic context components: function, plane-mask, line-width, line-style,
cap-style, join-style, fill-style, subwindow-mode, clip-x, clip-y, and
clip-mask.  Both functions also use these graphic context mode-dependent
components: foreground, background, tile, stipple, ts-x-origin, ts-y-origin,
dash-offset, and dash-list.



(DEFUN draw-arc (drawable gcontext x y width height angle1 angle2 &optional fill-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE int16 x y)
           (TYPE card16 width height)
           (TYPE angle angle1 angle2)
           (TYPE boolean fill-p)))


drawable
        Specifies the drawable which will receive the arc.

gcontext
        Specifies the graphic context to draw the arc with.

x
y       Specify the x and y coordinates.  These are the coordinates of the
        arc and are relative to the ORIGIN of the drawable.  These
        coordinates also specify the upper left corner of the rectangle.

width
height  Specify the width and height.  These are the major and minor axes of
        the arc.

angle1  Specifies the start of the arc relative to the three-o-clock
        position from the center, in units of radians and bounded by (* -2 pi)
        and (* 2 pi).

angle2  Specifies the path and extent of the arc relative to the start of
        the arc, in units of radians and bounded by (* -2 pi) and (* 2 pi).

fill-p  Specifies whether the arc is to be drawn as an outline or to be
        drawn filled.

Draw-arc draws either circular or elliptical, outlined or filled arcs.  Each
arc is specified by a rectangle and two angles.  The angles are signed
integers in radians, with positive indicating counterclockwise motion and
negative indicating clockwise motion.  The start of the arc is specified by
angle1 relative to the three-o'clock position from the center of the rectangle,
and the path and extent of the arc is specified by angle2 relative to the
start of the arc.  If the magnitude of angle2 is greater than 360 degrees, it
is truncated to 360 degrees.  The x and y coordinates of the rectangle are
relative to the origin of the drawable.  For an arc specified as
[x,y,w,h,a1,a2], the origin of the major and minor axes is at
[x+(w/2),y+(h/2)], and the infinitely thin path describing the entire
circle/ellipse intersects the horizontal axis at [x,y+(h/2)] and
[x+w,y+(h/2)], and intersects the vertical axis at [x+(w/2),y] and
[x+(w/2),y+h].  These coordinates can be fractional, i.e., they are not
truncated to discrete coordinates.  Note that the angle values are slightly
different in CLX than in the Xlib document and the protocol specification.


(DEFUN draw-arcs (drawable gcontext arcs &optional fill-p)
  (DECLARE (TYPE drawable drawable)
           (TYPE gcontext gcontext)
           (TYPE arc-seq arcs)
           (TYPE boolean fill-p)))

drawable
        Specifies the drawable which will receive the arcs.

gcontext
        Specifies the graphic context under which the arcs will be drawn.

x
y       Specify the x and y coordinates.  These are the coordinates of the
        arc and are relative to the ORIGIN of the drawable.  These
        coordinates also specify the upper left corner of the rectangle.

arcs    A list <?> containing the width,height,angle1, and angle2
        descriptors defining the arcs.  see draw-arc for more detail.

fill-p  Specifies whether the arcs are to be drawn as outlines or to be
        drawn filled.

Draw-arcs draws circular or elliptical, outlined or filled arcs.  Each arc
is specified by a rectangle and two angles with in the arcs parameter.
For a more detailed description see Draw-Arc.

The arcs are filled in the order listed.  For any given arc, no pixel is
drawn more than once.  If regions intersect, the intersecting pixels are
drawn multiple times.



                   Chapter 8

              Events and Event-Handling Functions

****----preliminary section designations

8.1. Event Types

8.2. Event Structures

8.3. Event Mask

8.4. Event Processing

8.4.1. Keyboard and Pointer Event Processing

8.4.1.1. Pointer Button Specific Processing

8.4.1.2. Common Keyboard and Pointer Event Processing

8.4.2. Window Entry/Exit Event Processing

8.4.2.1. Normal Entry/Exit Event Processing

8.4.2.2. Grab and Ungrab Entry/Exit Event Processing

8.4.3. Input Focus Events

8.4.3.1. Normal and While Grabbed Focus Event Processing

8.4.3.2. Focus Events Generated by Grabs

8.4.4. Key Map State Notification Event Processing

8.4.5. Exposure Event Processing

8.4.5.1. Expose Event Processing

8.4.5.2. GraphicsExpose and NoExpose Event Processing

8.4.6. Window State Notification Event Processing
8.4.6.1. CirculateNotify Event Processing
8.4.6.2. ConfigureNotify Event Processing
8.4.6.3. CreateNotify Event Processing
8.4.6.4. DestroyNotify Event Processing
8.4.6.5. GravityNotify Event Processing
8.4.6.6. MapNotify Event Processing
8.4.6.7. MappingNotify Event Processing
8.4.6.8. ReparentNotify Event Processing
8.4.6.9. UnmapNotify Event Processing
8.4.6.10. VisibilityNotify Event Processing
8.4.7. Structure Control Event Processing
8.4.7.1. CirculateRequest Event
8.4.7.2. ConfigureRequest Event
8.4.7.3. MapRequest Event
8.4.7.4. ResizeRequest Event Processing

8.4.8. Color Map State Notification Event Processing

8.4.9. Client Communication Event Processing
8.4.9.1. ClientMessage Event Processing
8.4.9.2. PropertyNotify Event Processing
8.4.9.3. SelectionClear Event Processing
8.4.9.4. SelectionRequest Event Processing
8.4.9.5. SelectionNotify Event Processing

8.5. Selecting Events

8.6. Handling the Output Buffer

8.7.  Event Queue Management

8.8. Manipulating the Event Queue

8.8.1. Returning the Next Event

8.8.2. Selecting Events Using a Predicate Procedure
8.8.3. Selecting Events Using a Window or Event Mask

8.9. Putting an Event Back onto the Queue


8.10. Sending Events to Other Applications


To send an event to a specified window, use send-event.  This function is
often used in selection processing.  For example, the owner of a selection
should use send-event to send a :selection-notify event to a requestor when a
selection has been converted and stored as a property.


(DEFUN send-event (window event-key event-mask &REST args
           &KEY propagate-p display &ALLOW-OTHER-KEYS)
  (DECLARE (TYPE (OR window (MEMBER :pointer-window :input-focus)) window)
       (TYPE (OR NULL event-key) event-key)
       (TYPE event-mask event-mask)
       (TYPE boolean propagate-p)
       (TYPE (OR NULL display) display)))

window  Specifies the window ID.  This is the window interested in the event,
        and is referred to as the destination window.  You can pass the window
        ID or either :pointer-window or :input-focus

event-key
        A user defined event-key or one of the following keywords: :key-press
        :key-release :button-press :button-release :motion-notify
        :enter-notify :leave-notify :focus-in :focus-out :keymap-notify
        :exposure :graphics-exposure :no-exposure :visibility-notify
        :create-notify :destroy-notify :unmap-notify :map-notify :map-request
        :reparent-notify :configure-notify :gravity-notify :resize-request
        :configure-request :circulate-notify :circulate-request
        :property-notify :selection-clear :selection-request :selection-notify
        :colormap-notify :client-message

event-mask
        This mask is the bit-wise inclusive OR of one or more of the valid
        event mask bits.  It may be a user defined event-mask or one of the
        following: :button-press :button-release :enter-window :leave-window
        :pointer-motion :pointer-motion-hint :button-1-motion :button-2-motion
        :button-3-motion :button-4-motion :button-5-motion :button-motion or
        :keymap-state.


:propagate-p
        Specifies a predicate that may be either True or NIL.

:display
        The display device receiving the event; usually optional, however, it
        is required for :pointer-window or :input-focus window options.



The send-event function identifies the destination window, determines which
clients should receive the specified events, and ignores any active grabs.
Additional arguments (args) depend on event-key, and are as specified further
below with declare-event, except that both resource-ids and resource objects
are accepted in the event components.  The display argument is only required
if the window is :pointer-window or :input-focus.


If :pointer-window is specified for the window argument, the event destination
window is replaced with the window containing the pointer.

If :input-focus is specified for the window argument, then the focus window
will receive the event.  However, if the focus window contains a child window
which contains the pointer, the child window will receive the event and not
the focus window. In the latter case, the focus window will receive the event
only if the :propagate-p predicate is True.

The event-key code must be one of the core events, or one of the events
defined by an extension, so that the server can correctly byte swap the
contents as necessary.  The contents of the event are otherwise unaltered and
unchecked by the server except to force on the most significant bit of the
event-key code.

If the event-mask is NIL, then the event is sent to the client that created
the destination window with an event-mask of 0; if that client no longer
exists, no event is sent.

If :propagate-p is NIL, then the event is sent to every client selecting
on the destination window. If window is specified as :input-focus, the event
will not propagate to the focus window.

If :propagate-p is True and no clients have selected (on the destination)
window any of the event types in event-mask, then window is replaced with the
closest ancestor of destination for which some client has selected a type in
event-mask and no intervening window has that type in its do-not-propagate
mask.  If no such window exists, or if the window is an ancestor of the focus
window and :input-focus was originally specified as the destination, then the
event is not sent to any clients.  Otherwise, the event is reported to every
client selecting on the final destination any of the types specified in
event-mask.



8.11. Getting Pointer Motion History

8.12. Handling Error Events

8.12.1. Enabling or Disabling Synchronization

8.12.2. Using the Default Error Handlers


    Chapter 9: Window Manager Functions

*preliminary section designations

    9.1.  Changing the Parent


9.2.  Lifetime of a Window

The functions described in this section are used to control the longevity of
subwindows that are normally destroyed when the parent is destroyed.  For
example, a window manager that wants to add decoration to a window by adding a
frame might reparent an application's window.  When the frame is destroyed,
the application's window should not be destroyed, but returned to its previous
place in the window hierarchy.

The save-set of a client is a list of other client's windows which, if they
are inferiors of one of the client's windows at connection close, should not
be destroyed and should be remapped if they are unmapped.  CLX provides the
add-to-save-set and remove-from-save-set functions to allow an application's
window to survive when a window manager that has reparented a window fails.
Although differing slightly from XLib, the CLX functions for add-to-save-set
and remove-from-save-set allow you to change a client's save-set, add a
subwindow to a client's save-set, or remove a subwindow from a client's
save-set.


Note that windows are removed automatically from the save-set by the X server
when they are destroyed.  For each window in the client's save-set, if the
window is an inferior of a window created by the client, the save-set window
is reparented to the closest ancestor such that the save-set window is not an
inferior of a window created by the client.  If the save-set window is
unmapped, a map-window request is performed on it.  After save-set processing,
all windows created by the client are destroyed.  For each non-window resource
created by the client, the appropriate Free request is performed.  All colors
and color map entries allocated by the client are freed.


(DEFUN remove-from-save-set (window)
  (DECLARE (TYPE window window)))

Remove-from-save-set removes the specified window from the client's
"save-set".  The window must have been created by some other client.  Windows
are removed automatically from the save-set by the server when they are
destroyed.


(DEFUN add-to-save-set (window)
  (DECLARE (TYPE window window)))

Add-to-save-set adds the specified window to the client's "save-set".  The
window must have been created by some other client.  Windows are removed
automatically from the save-set by the server when they are destroyed.




    9.3.  Resident Colormap Determination

    9.4.  Grab Operations

    9.4.1. Grabbing the pointer

    9.4.2. Grabbing a button

    9.4.3.  Grabbing the Keyboard

    9.4.4.  Grabbing a key

    9.4.5.  Grabbing the Server


9.4.1. Grabbing the pointer


(DEFUN grab-pointer (window event-mask
             &KEY owner-p sync-pointer-p sync-keyboard-p
                          confine-to cursor time)
  (DECLARE (TYPE window window)
       (TYPE pointer-event-mask event-mask)
       (TYPE boolean :owner-p :sync-pointer-p :sync-keyboard-p)
       (TYPE (OR NULL window) :confine-to)
       (TYPE (OR NULL cursor) :cursor)
       (TYPE timestamp :time)
       (VALUES grab-status)
       (TYPE (MEMBER :success :already-grabbed :invalid-time
                         :not-viewable :frozen) grab-status)))

window
    The window whose pointer is to be grabbed.

event-mask
        May be one of the following: :button-press :button-release
        :enter-window :leave-window :pointer-motion :pointer-motion-hint
    :button-1-motion :button-2-motion :button-3-motion :button-4-motion
    :button-5-motion :button-motion or :keymap-state.

:owner-p
    is a boolean which indicates if the window is the owner.

:sync-pointer-p
    is a predicate which indicates whether the pointer is in synchronous
    or asynchronous mode.

:sync-keyboard-p
    is a predicate which indicates whether the keyboard is in synchronous
    or asynchronous mode.

:confine-to
    indicates a window in which the pointer is confined to.

:cursor     The value of the cursor, or none.

:time    is either a timestamp or current-time


Grab-Pointer actively grabs control of the pointer.  Further pointer events
are only reported to the grabbing client.  The request overrides any active
pointer grab by this client.

If :owner-p is NIL, all generated pointer events are reported with respect to
window, and are only reported if selected by event-mask.  If :owner-p is True,
and if a generated pointer event would normally be reported to this client, it
is reported normally; otherwise the event is reported with respect to the
window, and is only reported if selected by event-mask.  For either value of
:owner-p, unreported events are simply discarded.

If :sync-pointer-p is NIL, pointer event processing continues (asynchronous)
normally; if the pointer is currently frozen by this client, then processing
of pointer events is resumed.  If :sync-pointer-p is T (indicating a
synchronous action) the pointer (as seen via the protocol) appears to freeze,
and no further pointer events are generated by the server until the grabbing
client issues a releasing allow-events request.  Actual pointer changes are
not lost while the pointer is frozen; they are simply queued for later
processing.

If :sync-keyboard-p is NIL, (indicating asynchronous action) keyboard event
processing is unaffected by activation of the grab.  If :sync-keyboard-p is
True, (indicating synchronous action) the keyboard (as seen via the protocol)
appears to freeze, and no further keyboard events are generated by the server
until the grabbing client issues a releasing allow-events request.  Actual
keyboard changes are not lost while the keyboard is frozen; they are simply
queued for later processing.

If :cursor is specified, then it is displayed regardless of what window the
pointer is in.  If :cursor is not specified, then when the pointer is in
window or one of its subwindows, the normal cursor for that window is
displayed, and otherwise the cursor for window is displayed.

If a :confine-to window is specified, then the pointer will be restricted or
"confined" to stay within that window.  The :confine-to window does not have to
have any relationship to the grab-window.  If the pointer is not initially in
the :confine-to window, then it is warped automatically to the closest edge
(with enter/leave events generated normally) just before the grab activates.
If the :confine-to window is subsequently reconfigured, the pointer will be
warped automatically as necessary to keep it contained in the window.

Grab-pointer generates enter-notify and leave-notify events.

Grab-pointer fails with a status of :already-grabbed if the pointer is
actively grabbed by some other client.  Grab-pointer fails with a status of
:frozen if the pointer is frozen by an active grab of another client.
Grab-pointer also fails with a status of :not-viewable if the grab-window or
the confine-to window is not viewable, or if the confine-to window lies
completely outside the boundaries of the root window.  Grab-pointer can also
fail with a status of :invalid-time if the specified time is earlier than the
last-pointer-grab time or later than the current server time.  Otherwise, the
last-pointer-grab time is set to the specified time, with current-time
replaced by the current server time, and a value of :success is returned by
grab-pointer.


(DEFUN ungrab-pointer (display &key time)
  (DECLARE (TYPE display display)
       (TYPE timestamp :time)))

display Specifies the display connection to the X server.

:time    A time stamp.

Ungrab-Pointer releases the pointer if this client has it actively grabbed
(from either grab-pointer or grab-button or from a normal button press), and
releases any queued events.  The request has no effect if the specified time
is earlier than the last-pointer-grab time or is later than the current server
time. An UngrabPointer is performed automatically if the event window or
confine-to window for an active pointer grab becomes not viewable.

This request generates enter-notify and leave-notify events.


Button grabbing

Buttons on the pointer may be passively "grabbed" by a client.  When the
button is pressed, the pointer is then actively grabbed by the client.


(DEFUN change-active-pointer-grab (display event-mask &OPTIONAL cursor time)
  (DECLARE (TYPE display display)
       (TYPE pointer-event-mask event-mask)
       (TYPE (OR NULL cursor) cursor)
       (TYPE timestamp time)))

display    Specifies the display connection to the X server.

event-mask
        May be one of the following: :button-press :button-release
        :enter-window :leave-window :pointer-motion :pointer-motion-hint
    :button-1-motion :button-2-motion :button-3-motion :button-4-motion
    :button-5-motion :button-motion or :keymap-state.


cursor     Optional. The value of the cursor, or none.

time    Optional. A time stamp or current time.


Changes the specified dynamic parameters if the pointer is actively grabbed by
the client and the specified time is no earlier than the last-pointer-grab
time and no later than the current server time.  The interpretation of
event-mask and cursor are as in grab-pointer.  change-active-pointer-grab has
no effect on the passive parameters of a grab-button.


9.4.2. Grabbing a button


(DEFUN grab-button (window button event-mask
            &KEY (modifiers 0)
             owner-p sync-pointer-p sync-keyboard-p confine-to cursor)
  (DECLARE (TYPE window window)
       (TYPE (OR (member :any) card8) button)
       (TYPE pointer-event-mask event-mask)
       (TYPE modifier-mask :modifiers)
       (TYPE boolean :owner-p :sync-pointer-p :sync-keyboard-p)
       (TYPE (OR NULL window) :confine-to)
       (TYPE (OR NULL cursor) :cursor)))

window
    The window whose pointer is to be grabbed.

button    The button pressed or :any.

event-mask
        May be one of the following: :button-press :button-release
        :enter-window :leave-window :pointer-motion :pointer-motion-hint
    :button-1-motion :button-2-motion :button-3-motion :button-4-motion
    :button-5-motion :button-motion or :keymap-state.

:modifiers
        Any of the modifier-keys: :shift :lock :control :mod-1 :mod-2 :mod-3
    :mod-4 or :mod-5.

:owner-p
    is a boolean which indicates if the window is the owner.

:sync-pointer-p
        is a predicate which indicates whether the pointer is handled in a
    synchronous or asynchronous fashion.

:sync-keyboard-p
    is a predicate which indicates whether the keyboard is in synchronous
    or asynchronous mode.

:confine-to
    indicates a window in which the pointer is confined to.

:cursor The value of the cursor, or none.


This request establishes a passive grab.  If the specified button is pressed
when the specified modifier keys are down (and no other buttons or modifier
keys are down), and window contains the pointer, and the confine-to window (if
any) is viewable, and these constraints are not satisfied for any ancestor,
then the pointer is actively grabbed as described with grab-pointer, the
last-pointer-grab time is set to the time at which the button was pressed (as
transmitted in the button-press event), and the button-press event is
reported.  The interpretation of the remaining arguments is the same as with
grab-pointer.  The active grab is terminated automatically when all buttons
are released (independent of the state of modifier keys).

A modifier is equivalent to issuing the request for all possible modifier-key
combinations (including the combination of no modifiers).  These are :shift
:lock :control :mod-1 :mod-2 :mod-3 :mod-4 and :mod-5.  It is not required
that all modifiers specified have currently assigned keycodes.  A button of
:any is equivalent to issuing the request for all possible buttons.
Otherwise, it is not required that the button specified currently be assigned
to a physical button.


(DEFUN ungrab-button (window button &KEY (modifiers 0))
  (DECLARE (TYPE window window)
       (TYPE (OR (member :any) card8) button)
       (TYPE modifier-mask :modifiers)))

window
    The window whose pointer is to be grabbed.

button    The button that is released or :any.

:modifiers
        Any of the modifier-keys: :shift :lock :control :mod-1 :mod-2 :mod-3
    :mod-4 or :mod-5.

Releases the passive button/key combination on the specified window if it was
grabbed by this client.  A modifier (of the modifier-key type) is equivalent
to issuing the request for all possible modifier combinations (including the
combination of no modifiers).  A button of :any is equivalent to issuing the
request for all possible buttons.  This has no effect on an active grab.




9.4.3.  Grabbing the Keyboard


(DEFUN grab-keyboard (window &KEY owner-p sync-pointer-p sync-keyboard-p time)
  (DECLARE (TYPE window window)
       (TYPE boolean :owner-p :sync-pointer-p :sync-keyboard-p)
       (TYPE timestamp :time)
       (VALUES grab-status)
       (TYPE (MEMBER :success :already-grabbed :invalid-time
                         :not-viewable :frozen) grab-status)))


window
    The window whose pointer is to be grabbed.

:owner-p
    is a boolean which indicates if the window is the owner.

:sync-pointer-p
    is a predicate which indicates whether the pointer is in synchronous
    or asynchronous mode.

:sync-keyboard-p
    is a predicate which indicates whether the keyboard is in synchronous
    or asynchronous mode.

:time    is either a timestamp or current-time


Grab-Keyboard actively grabs control of the keyboard.  Further key events are
reported only to the grabbing client.  The request overrides any active
keyboard grab by this client.

If owner-p is NIL, all generated key events are reported with respect to
window.  If owner-p is True, then if a generated key event would normally be
reported to this client, it is reported normally; otherwise the event is
reported with respect to the window.  Both :key-press and :key-release events
are always reported, independent of any event selection made by the client.

If sync-keyboard-p is NIL (Asynchronous), keyboard event processing continues
normally; if the keyboard is currently frozen by this client, then processing
of keyboard events is resumed.  If sync-keyboard-p is True (Synchronous), the
keyboard (as seen via the protocol) appears to freeze, and no further keyboard
events are generated by the server until the grabbing client issues a
releasing Allow-events request.  Actual keyboard changes are not lost while the
keyboard is frozen; they are simply queued for later processing.

If sync-pointer-p is NIL (asynchronous), pointer event processing is
unaffected by activation of the grab.  If sync-pointer-p is True
(synchronous), the pointer (as seen via the protocol) appears to freeze, and
no further pointer events are generated by the server until the grabbing
client issues a releasing Allow-events request.  Actual pointer changes are not
lost while the pointer is frozen; they are simply queued for later processing.

Grab-keyboard generates focus-in and focus-out events.

The grab can fail with a status of :already-grabbed if the keyboard is
actively grabbed by some another client.  The grab fails with a status of
:frozen if the keyboard is frozen by an active grab from another client.  The
grab can fail with a status :not-viewable if grab-window is not viewable.  The
grab can fail with a status of :invalid-time if the specified time is earlier
than the last-keyboard-grab time or later than the current server time.
Otherwise, grab-keyboard returns a status of :success and last-keyboard-grab
time is set to the specified time with current-time replaced by the current
server time.



(DEFUN ungrab-keyboard (display &KEY time)
  (DECLARE (TYPE display display)
       (TYPE timestamp :time)))

display    Specifies the display connection to the X server.

:time    Optional. A timestamp or current time.

Releases the keyboard if this client has it actively grabbed (from either
grab-keyboard or grab-key), and releases any queued events.  The request has
no effect if the specified time is earlier than the last-keyboard-grab time or
is later than the current server time.  An Ungrab-Keyboard is performed
automatically if the event window for an active keyboard grab becomes not
viewable.



9.4.4.  Grabbing a key


(DEFUN grab-key (window key &KEY (modifiers 0) owner-p sync-pointer-p sync-keyboard-p)
  (DECLARE (TYPE window window)
       (TYPE (OR (member :any) card8) key)
       (TYPE modifier-mask :modifiers)
       (TYPE boolean :owner-p :sync-pointer-p :sync-keyboard-p)))

window
    The window whose key is to be grabbed.

key    The key to be grabbed or :any.

:modifiers
        0 (default) or any of the modifier-keys: :shift :lock :control :mod-1
    :mod-2 :mod-3 :mod-4 or :mod-5.

:owner-p
    is a boolean which indicates if the window is the owner.

:sync-pointer-p
    is a predicate which indicates whether the pointer is in synchronous
    or asynchronous mode.

:sync-keyboard-p
    is a predicate which indicates whether the keyboard is in synchronous
    or asynchronous mode.

:time    is either a timestamp or current-time


This request establishes a passive grab on the keyboard.  If the specified key
(which can itself be a modifier key) is pressed (whether or not any specified
modifier keys are down), and either a) window is an ancestor of (or is) the
focus window or b) window is a descendant of the focus window and contains the
pointer, and these constraints are not satisfied for any ancestor of window,
then the keyboard is actively grabbed as described in grab-keyboard, the
last-keyboard-grab time is set to the time at which the key was pressed (as
transmitted in the Key-Press event), and the key-press event is reported.  The
interpretation of the remaining arguments is as for grab-keyboard.  The active
grab is terminated (independent of the state of the modifier keys)
automatically when the specified key has been released.


A modifier key of :any is equivalent to issuing the request for all possible
modifier combinations (including the combination of no modifiers).  It is not
required that all modifiers specified have currently assigned keycodes.  A key
of :Any is equivalent to issuing the request for all possible keycodes.
Otherwise, the key must be in the range specified by min-keycode and
max-keycode in the connection setup.


(DEFUN ungrab-key (window key &KEY (modifiers 0))
  (DECLARE (TYPE window window)
       (TYPE (OR (MEMBER :any) card8) key)
       (TYPE modifier-mask :modifiers)))

window
    The window whose key is to be grabbed.

key    The key to be grabbed or :any.

:modifiers
        0 (default) or any of the modifier-keys: :shift :lock :control :mod-1
    :mod-2 :mod-3 :mod-4 or :mod-5.

Ungrab-Key releases the key combination on the specified window if it was
grabbed by this client.  A modifiers of :any is equivalent to issuing the
request for all possible modifier combinations (including the combination of
no modifiers).  A key of :any is equivalent to issuing the request for all
possible keycodes.  Ungrab-Key has no effect on an active grab.




9.4.5.  Grabbing the Server


(DEFMACRO with-server-grabbed ((display) &body body)
  ;; The body is not surrounded by a with-display.
  )


(DEFUN grab-server (display)
  (DECLARE (TYPE display display)))

display    Specifies the display connection to the X server.


Disables processing of requests and close-downs on all connections other than
the one this request arrived on.


Ungrab-Server


(DEFUN ungrab-server (display)
  (DECLARE (TYPE display display)))

display    Specifies the display connection to the X server.

Restarts processing of requests and close-downs on other connections.




    9.5.  Miscellaneous Control Functions

    9.6.  Keyboard Settings

    9.7.  Keyboard Encodings

    9.8. Screen Saver Utility

    9.9. Controlling Host Access





                 Chapter ??

                 Defining Extensions


(DEFMACRO define-gcontext-accessor (name &key default set-function
                                              copy-function)
  (DECLARE (TYPE symbol name)
           (TYPE t :default)
           (TYPE (FUNCTION (gcontext t) t) :set-function) ;; required
           (TYPE (OR null (FUNCTION (gcontext gcontext t) t))
                 :copy-function)))

name

:default

:set-function

:copy-function


This will define a new graphic context accessor called NAME.  Defines the
gcontext-NAME accessor function and its defsetf.  Graphic contexts will cache
DEFAULT-VALUE and the last value SETFED when gcontext-cache-p is true.  The
NAME keyword will be allowed in CREATE-GCONTEXT, WITH-GCONTEXT, and
COPY-GCONTEXT-COMPONENTS.  SET-FUNCTION will be called with parameters
(GCONTEXT NEW-VALUE) from create-gcontext, and force-gcontext-changes.
COPY-FUNCTION will be called with parameters (src-gc dst-gc src-value) from
copy-gcontext and copy-gcontext-components.  The copy-function defaults to:
        (lambda (IGNORE dst-gc value)
          (IF value
              (,set-function dst-gc value)
              (ERROR "Can't copy unknown GContext component ~a" ',name)))






Appendix


Glossary of Terms




Access control list

        X maintains a list of hosts from which client programs may be run.  By
        default, only programs on the local host may use the display, plus any
        hosts specified in an initial list read by the server.  This "access
        control list" can be changed by clients on the local host.  Some
        server implementations may also implement other authorization
        mechanisms in addition to or in place of this mechanism.  The action
        of this mechanism may be conditional based on the authorization
        protocol name and data received by the server at connection setup.

Active grab

        A grab is "active" when the pointer or keyboard is actually owned by
        the single grabbing client.

Ancestors

        If W is an inferior of A, then A is an "ancestor" of W.

Atom

        An "atom" is a unique id corresponding to a string name.  Atoms are
        used to identify properties, types, and selections.

Backing store

        When a server maintains the contents of a window, the off-screen saved
        pixels are known as a "backing store".

Bit gravity

        When a window is resized, the contents of the window are not
        necessarily discarded.  It is possible to request the server (though
        no guarantees are made) to relocate the previous contents to some
        region of the window.  This attraction of window contents for some
        location of a window is known as "bit gravity".

Bitmap

        A "bitmap" is a pixmap of depth one.

Button grabbing

        Buttons on the pointer may be passively "grabbed" by a client.  When
        the button is pressed, the pointer is then actively grabbed by the
        client.

Byte order

        For image (pixmap/bitmap) data, byte order is defined by the server,
        and clients with different native byte ordering must swap bytes as
        necessary.  For all other parts of the protocol, the byte order is
        defined by the client, and the server swaps bytes as necessary.

Children

        The "children" of a window are its first-level subwindows.

Client

        An application program connects to the window system server by some
        interprocess communication (IPC) path, such as a TCP connection or a
        shared memory buffer.  This program is referred to as a "client" of
        the window system server.  More precisely, the client is the IPC path
        itself; a program with multiple paths open to the server is viewed as
        multiple clients by the protocol.  Resource lifetimes are controlled
        by connection lifetimes, not by program lifetimes.

Clipping regions

        In a graphic context, a bitmap or list of rectangles can be specified
        to restrict output to a particular region of the window.  The image
        defined by the bitmap or rectangles is called a "clipping region".

Colormap

        A "colormap" consists of a set of entries defining color values.  The
        colormap associated with a window is used to display the contents of
        the window; each pixel value indexes the colormap to produce RGB
        values that drive the guns of a monitor.  Depending on hardware
        limitations, one or more colormaps may be installed at one time, such
        that windows associated with those maps display with correct colors.

Connection

        The IPC path between the server and client program is known as a
        "connection".  A client program typically (but not necessarily) has
        one connection to the server over which requests and events are sent.

Containment

        A window "contains" the pointer if the window is viewable and the
        hotspot of the cursor is within a visible region of the window or a
        visible region of one of its inferiors.  The border of the window is
        included as part of the window for containment.  The pointer is "in" a
        window if the window contains the pointer but no inferior contains the
        pointer.

Coordinate system

        The coordinate system has X horizontal and Y vertical, with the origin
        [0, 0] at the upper left.  Coordinates are discrete, and in terms of
        pixels.  Each window and pixmap has its own coordinate system.  For a
        window, the origin is at the inside upper left, inside the border.

Cursor

        A "cursor" is the visible shape of the pointer on a screen.  It
        consists of a hot spot, a source bitmap, a shape bitmap, and a pair of
        colors.  The cursor defined for a window controls the visible
        appearance when the pointer is in that window.

Depth

        The "depth" of a window or pixmap is number of bits per pixel it has.
        The depth of a graphic context is the depth of the drawables it can
        be used in conjunction with for graphics output.

Device

        Keyboards, mice, tablets, track-balls, button boxes, etc.  are all
        collectively known as input "devices".  The core protocol only deals
        with two devices, "the keyboard" and "the pointer".

Direct Color

        A class of colormap in which a pixel value is decomposed into three
        separate subfields for indexing.  One subfield indexes an array to
        produce red intensity values, the second subfield indexes a second
        array to produce blue intensity values, and the third subfield indexes
        a third array to produce green intensity values.  The RGB values can
        be changed dynamically.

Drawable

        Both windows and pixmaps may be used as sources and destinations in
        graphics operations.  These are collectively known as "drawables".
        However, an Input-only window cannot be used as a source or destination
        in a graphics operation.

Event

        Clients are informed of information asynchronously via "events".
        These events may be either asynchronously generated from devices, or
        generated as side effects of client requests.  Events are grouped into
        types; events are never sent to a client by the server unless the
        client has specifically asked to be informed of that type of event,
        but other clients can force events to be sent to other clients.
        Events are typically reported relative to a window.

Event mask

        Events are requested relative to a window.  The set of event types a
        client requests relative to a window described using an "event mask".

Event synchronization

        There are certain race conditions possible when demultiplexing device
        events to clients (in particular deciding where pointer and keyboard
        events should be sent when in the middle of window management
        operations).  The event synchronization mechanism allows synchronous
        processing of device events.

Event propagation

        Device-related events "propagate" from the source window to ancestor
        windows until some client has expressed interest in handling that type
        of event, or until the event is discarded explicitly.

Event source

        The smallest window containing the pointer is the "source" of a device
    related event.

Exposure event

        Servers do not guarantee to preserve the contents of windows when
        windows are obscured or reconfigured.  "Exposure" events are sent to
        clients to inform them when contents of regions of windows have been
        lost.

Extension

        Named "extensions" to the core protocol can be defined to extend the
        system.  Extension to output requests, resources, and event types are
        all possible, and expected.

Focus window

    The "focus window" is another term for the input focus.

Font

        A "font" is a matrix of glyphs (typically characters).  The protocol
        does no translation or interpretation of character sets.  The client
        simply indicates values used to index the glyph array.  A font
        contains additional metric information to determine inter-glyph and
        inter-line spacing.

Glyph

        A "glyph" is an image, typically of a character, in a font.

Grab

        Keyboard keys, the keyboard, pointer buttons, the pointer, and the
        server can be "grabbed" for exclusive use by a client.  In general,
        these facilities are not intended to be used by normal applications,
        but are intended for various input and window managers to implement
        various styles of user interfaces.

Gray Scale

        Gray Scale can be viewed as a degenerate case of Pseudo Color, in
        which the red, green, and blue values in any given colormap entry are
        equal, thus producing shades of gray.  The gray values can be changed
        dynamically.

GC, GContext

    Shorthand for "graphic context".

Graphic context

        Various information for graphics output is stored in a "graphic
        context" (or "GC" or "gcontext"), such as foreground pixel, background
        pixel, line width, clipping region, etc.  A graphic context can only
        be used with drawables that have the same root and the same depth as
        the graphic context.

Hotspot

        A cursor has an associated "hot spot" which defines a point in the
        cursor that corresponds to the coordinates reported for the pointer.

Identifier

        Each resource has an "identifier", a unique value associated with it
        that clients use to name the resource.  An identifier can be used over
        any connection to name the resource.

Inferiors

        The "inferiors" of a window are all of the subwindows nested below it:
        the children, the children's children, etc.

Input focus

        The "input focus" is normally a window defining the scope for
        processing of keyboard input.  If a generated keyboard event would
        normally be reported to this window or one of its inferiors, the event
        is reported normally; otherwise, the event is reported with respect to
        the focus window.  The input focus also can be set such that all
        keyboard events are discarded, and also can be set such that the focus
        window is dynamically taken to be the root window of whatever screen
        the pointer is on at each keyboard event.

Input manager

        Control over keyboard input is typically provided by an "input
    manager" client.

Input-Only window

        A window that cannot be used for graphics requests.  Input-Only windows
        are "invisible", and can be used to control such things as cursors,
        input event generation, and grabbing.  Input-Only windows cannot have
        Input/Output windows as inferiors.

Input/Output window

        The "normal" kind of opaque window, used for both input and output.
        Input/Output windows can have both Input/Output and Input-Only windows as
        inferiors.

Key grabbing

        Keys on the keyboard may be passively "grabbed" by a client.  When the
        key is pressed, the keyboard is then actively grabbed by the client.

Keyboard grabbing

        A client can actively "grab" control of the keyboard, and key events
        will be sent to that client rather than the client the events would
        normally have been sent to.

Keysym

    An encoding of a symbol on a keycap on a keyboard.

Mapped

        A window is said to be "mapped" if a map call has been performed on
        it.  Unmapped windows and their inferiors are never viewable or
        visible.

Modifier keys

        Shift, Control, Meta, Super, Hyper, ALT, Compose, Apple, CapsLock,
        ShiftLock, and similar keys are called "modifier" keys.

Monochrome

        A special case of Static Gray, in which there are only two colormap
    entries.

Obscure

        A window is "obscured" if some other window "obscures" it.  Window A
        "obscures" window B if both are viewable Input/Output windows and A is
        higher in the global stacking order, and the rectangle defined by the
        outside edges of A intersects the rectangle defined by the outside
        edges of B.  Note the (fine) distinction with "occludes".  Also note
        that window borders are included in the calculation.  Also note that a
        window can be obscured and yet still have visible regions.

Occlude

        A window is "occluded" if some other window "occludes" it.  Window A
        "occludes" window B if both are mapped and A is higher in the global
        stacking order, and the rectangle defined by the outside edges of A
        intersects the rectangle defined by the outside edges of B.  Note the
        (fine) distinction with "obscures".  Also note that window borders are
        included in the calculation.

Padding

        Some padding bytes are inserted in the data stream to maintain
        alignment of the protocol requests on natural boundaries.  This
        increases ease of portability to some machine architectures.

Parent window

        If C is a child of P, then P is the "parent" of C.

Passive grab

    Grabbing a key or button is a "passive" grab.  The grab activates when the key or
    button is actually pressed.

Pixel value

        A "pixel" is an N-bit value, where N is the number of bit planes used
        in (i.e., the depth of) a particular window or pixmap.  For a window,
        a pixel value indexes a colormap to derive an actual color to be
        displayed.

Pixmap

        A "pixmap" is a three dimensional array of bits.  A pixmap is normally
        thought of as a two dimensional array of pixels, where each pixel can
        be a value from 0 to (2^N)-1, where N is the depth (z axis) of the
        pixmap.  A pixmap can also be thought of as a stack of N bitmaps.

Plane

        When a pixmap or window is thought of as a stack of bitmaps, each
        bitmap is called a "plane" or "bit plane".

Plane mask

        Graphics operations can be restricted to only affect a subset of bit
        planes of a destination.  A "plane mask" is a bit mask describing
        which planes are to be modified, and is stored in a graphic context.

Pointer

        The "pointer" is the pointing device attached to the cursor, and
    tracked on the screens.

Pointer grabbing

        A client can actively "grab" control of the pointer, and button and
        motion events will be sent to that client rather than the client the
        events would normally have been sent to.

Pointing device

        A "pointing device" is typically a mouse or tablet, or some other
        device with effective dimensional motion.  There is only one visible
        cursor is defined by the core protocol, and it tracks whatever
        pointing device is attached as the pointer.

Property

        Windows may have associated "properties", consisting of a name, a
        type, a data format, and some data.  The protocol places no
        interpretation on properties, they are intended as a general-purpose
        naming mechanism for clients.  For example, clients might share
        information such as resize hints, program names, and icon formats with
        a window manager via properties.

Property list

        The "property list" of a window is the list of properties that have
        been defined for the window.

Pseudo Color

        A class of colormap in which a pixel value indexes the colormap to
        produce independent red, green, and blue values.  That is, the
        colormap is viewed as an array of triples (RGB values).  The RGB
        values can be changed dynamically.

Redirecting control

        Window managers (or client programs) may wish to enforce window layout
        policy in various ways.  When a client attempts to change the size or
        position of a window, the operation may be "redirected" to a specified
        client, rather than the operation actually being performed.

Reply

        Information requested by a client program is sent back to the client
        with a "reply".  Both events and replies are multiplexed on the same
        connection.  Most requests do not generate replies.  Some requests
        generate multiple replies.

Request

        A command to the server is called a "request".  It is a single block
        of data sent over a connection.

Resource

        Windows, pixmaps, cursors, fonts, graphic contexts, and colormaps are
        known as "resources".  They all have unique identifiers associated
        with them for naming purposes.  The lifetime of a resource is bounded
        by the lifetime of the connection over which the resource was created.

RGB values

        "Red, Green, and Blue" intensity values used to define color.  These
        values are always represented as 16 bit unsigned numbers, with zero
        being minimum intensity and 65535 being the maximum intensity.  The
        values are scaled by the server to match the display hardware.

Root

        The "root" of a pixmap or graphic context is the same as the root of
        whatever drawable was used when the pixmap or graphic context was
        created.  The "root" of a window is the root window under which the
        window was created.

Root window

        Each screen has a "root window" covering it.  It cannot be
        reconfigured or unmapped, but otherwise acts as a full fledged window.
        A root window has no parent.

Save set

        The "save set" of a client is a list of other client's windows which,
        if they are inferiors of one of the client's windows at connection
        close, should not be destroyed, and which should be remapped if it is
        unmapped.  Save sets are typically used by window managers to avoid
        lost windows if the manager should terminate abnormally.

Scanline

        A "scanline" is a list of pixel or bit values viewed as a horizontal
        row (all values having the same y coordinate) of an image, with the
        values ordered by increasing x coordinate.

Scanline order

        An image represented in "scanline order" contains scanlines ordered by
        increasing y coordinate.

Screen

        A server may provide several independent "screens", which typically
        have physically independent monitors.  This would be the expected
        configuration when there is only a single keyboard and pointer shared
        among the screens.

Selection

        A "selection" can be thought of as an indirect property with dynamic
        type.  That is, rather than having the property stored in the server,
        it is maintained by some client (the "owner").  A selection is global
        in nature, being thought of as belonging to the user (but maintained
        by clients), rather than being private to a particular window
        subhierarchy or a particular set of clients.  When a client asks for
        the contents of a selection, it specifies a selection "target type".
        This target type can be used to control the transmitted representation
        of the contents.  For example, if the selection is "the last thing the
        user clicked on", and that is currently an image, then the target type
        might specify whether the contents of the image should be sent in
        XYFormat or ZFormat.  The target type can also be used to control the
        class of contents transmitted; e.g., asking for the "looks" (fonts,
        line spacing, indentation, etc.) of a paragraph selection, rather than
        the text of the paragraph.  The target type can also be used for other
        purposes; the semantics is not constrained by the protocol.

Server

        The "server" provides the basic windowing mechanism.  It handles IPC
        connections from clients, demultiplexes graphics requests onto the
        screens, and multiplexes input back to the appropriate clients.

Server grabbing

        The server can be "grabbed" by a single client for exclusive use.
        This prevents processing of any requests from other client connections
        until the grab is complete.  This is typically only a transient state
        for such things as rubber-banding and pop-up menus, or to execute
        requests indivisibly.

Sibling

        Children of the same parent window are known as "sibling" windows.

Static Color

        Static Color can be viewed as a degenerate case of Pseudo Color, in
        which the RGB values are predefined and read-only.

Static Gray

        Static Gray can be viewed as a degenerate case of Gray Scale, in which
        the gray values are predefined and read-only.  The values are
        typically (near-)linear increasing ramps.

Stacking order

        Sibling windows may "stack" on top of each other.  Windows above both
        obscure and occlude lower windows.  This is similar to paper on a
        desk.  The relationship between sibling windows is known as the
        "stacking order".

Stipple

        A "stipple pattern" is a bitmap that is used to tile a region to serve
        as an additional clip mask for a fill operation with the foreground
        color.

Tile

        A pixmap can be replicated in two dimensions to "tile" a region.  The
        pixmap itself is also known as a "tile".

Timestamp

        A time value, expressed in milliseconds, typically since the last
        server reset.  Timestamp values wrap around (after about 49.7 days).
        The server, given its current time is represented by timestamp T,
        always interprets timestamps from clients by treating half of the
        timestamp space as being earlier in time than T, and half of the
        timestamp space as being later in time than T.  One timestamp value
        (named CurrentTime) is never generated by the server; this value is
        reserved for use in requests to represent the current server time.

True Color

        True Color can be viewed as a degenerate case of Direct Color, in
        which the subfields in the pixel value directly encode the
        corresponding RGB values.  That is, the colormap has predefined
        read-only RGB values.  The values are typically (near-)linear
        increasing ramps.

Type

        A type is an arbitrary atom used to identify the interpretation of
        property data.  Types are completely uninterpreted by the server; they
        are solely for the benefit of clients.

Viewable

        A window is "viewable" if it and all of its ancestors are mapped.
        This does not imply that any portion of the window is actually
        visible.  Graphics requests can be performed on a window when it is
        not viewable, but output will not be retained unless the server is
        maintaining backing store.

Visible

        A region of a window is "visible" if someone looking at the screen can
        actually "see" it: the window is viewable and the region is not
        occluded by any other window.

Window gravity

        When windows are resized, subwindows may be repositioned automatically
        relative to some position in the window.  This attraction of a
        subwindow to some part of its parent is known as "window gravity".

Window manager

        Manipulation of windows on the screen, and much of the user interface
        (policy) is typically provided by a "window manager" client.

XYFormat

        The data for a pixmap is said to be in "XYFormat" if it is organized
        as a set of bitmaps representing individual bit planes, with the
        planes appearing from most to least significant in bit order.

ZFormat

        The data for a pixmap is said to be in "ZFormat" if it is organized as
        a set of pixel values in scanline order.